Logging
By default, vCluster writes logs to the control plane pod using a human-readable console format. This format is easy to scan and works well when reviewing logs manually with tools such as kubectl logs.
You can alternatively configure the control plane to output logs in JSON format, which provides structured data compatible with external log aggregation tools (such as Elasticsearch). JSON logs simplify log collection, parsing, and analysis across multiple virtual clusters.
Log encoding formats​
vCluster supports two log encoding formats for the vCluster control plane pod.
- Console (Default): Human-readable format, recommended for development and manual log review.
- JSON: Structured format for log aggregation, commonly used with external monitoring and analysis tools.
Console format​
The console format provides human-readable logs with timestamps, log levels, source locations, and contextual information. This format works well for use cases where users are troubleshooting a single virtual cluster. Choose this format in environments where human readability is more important than structured log parsing. Example use cases include:
- Local development and testing, where developers benefit from quick, readable output.
- Single virtual cluster analysis, where users manually review logs and debug in a terminal.
2025-06-16 04:43:25 INFO license loader/inject.go:52 initializing license... {"component": "vcluster"}
2025-06-16 04:43:25 INFO license loader/inject.go:59 detected license type {"component": "vcluster", "licenseType": "Online"}
2025-06-16 04:43:29 INFO online/license.go:141 Enabled features: {"component": "vcluster"}
2025-06-16 04:43:29 INFO online/license.go:146 rancher-integration {"component": "vcluster"}
JSON format​
The JSON format structures log data for programmatic processing and integration with log management systems. This format is works well for use cases where external tools monitor and analyze logs for multiple virtual clusters. Log aggregation tools (such as Elasticsearch or Splunk) can import these logs to support automated analysis, alerting, and integration with monitoring platforms (for example, Prometheus and Grafana). Example use cases include:
- Production environments where you monitor multiple virtual clusters and require automatic parsing and processing of logs.
{"level":"info","ts":1750160027.442782,"logger":"license","caller":"loader/inject.go:52","msg":"initializing license...","component":"vcluster"}
{"level":"info","ts":1750160027.4497442,"logger":"license","caller":"loader/inject.go:59","msg":"detected license type","component":"vcluster","licenseType":"Online"}
{"level":"info","ts":1750160029.1307533,"caller":"online/license.go:141","msg":"Enabled features:","component":"vcluster"}
{"level":"info","ts":1750160029.1307998,"caller":"online/license.go:146","msg":"connected-clusters","component":"vcluster"}
JSON log fields​
Each JSON log entry contains the following standard fields:
| Field | Type | Description |
|---|---|---|
level | string | Log level (info, warn, error, debug) |
ts | number | Unix timestamp (seconds since epoch) |
caller | string | Source file and line number |
msg | string | Log message content |
component | string | vCluster component that generated the log |
Additional fields might be displayed based on context and log content.
Enable log encoding​
Configure logging in your vcluster.yaml configuration file.
To enable JSON-formatted logs, set the log encoding to json:
logging:
encoding: json
To disable JSON logging and return to the default console format, you can either remove the logging field entirely or explicitly set the format to console:
logging:
encoding: console
When changing between encoding formats, the Pod restarts and all previous logs are lost.