Logging and tracing

Clustron Zaris produces two independent kinds of diagnostic signal, configured separately:

• Logs — human-readable text about what a node and its manager are doing. Always available, written to the console and/or a rolling file.
• Traces and metrics — structured OpenTelemetry (OTLP) telemetry for dashboards and distributed tracing. Off by default; you opt in and point it at a collector.

This page covers how to configure both. For the list of metric instruments Zaris emits, see Observability; for the complete config schema, see the configuration reference.

Logging

A store's logging is set in the logging block of its store configuration. It controls the log level per category and the two sinks — console and a rolling file.

{
  "logging": {
    "logLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "System": "Warning",
      "Clustron.Nodus.Core": "Information",
      "Clustron.Zaris": "Information"
    },
    "console": { "enabled": true },
    "file": {
      "enabled": true,
      "path": "logs/zaris.log",
      "rollingInterval": "Day"
    }
  }
}

Setting	Type	Default	Description
logging.logLevel	map of category → level	{} (empty)	Minimum level per category. Level names are the standard .NET set: Trace, Debug, Information, Warning, Error, Critical, None. Use Default for the fallback and Clustron.Zaris / Clustron.Nodus.Core to tune Zaris and clustering output.
logging.console.enabled	bool	false	Write logs to the console sink.
logging.file.enabled	bool	false	Write logs to a rolling file.
logging.file.path	string	logs/zaris.log	File-sink path.
logging.file.rollingInterval	string	Day	How often the file rolls (for example Day).

note

The two sinks default to disabled in code, but the configuration shipped by the installer enables both the console and a daily rolling file, so a fresh install logs out of the box. Set enabled to false to turn a sink off.

A related top-level setting controls how often the cluster-membership summary is logged:

Setting	Type	Default	Description
logClusterViewIntervalSeconds	int	10	How often each node logs a one-line summary of its view of cluster membership.

Client-side logging

The .NET client writes its own diagnostics. Set a log-file path when you build the client, or bind it from the Zaris configuration section:

Setting	Type	Default	Description
LogFilePath (Zaris:LogFilePath)	string	none	Path for the client SDK's log file. Also settable in code via the client builder's WithLogFile.

Tracing and metrics (OpenTelemetry)

Zaris has native OpenTelemetry instrumentation: distributed traces from its internal activity source and a metrics meter (the per-operation latency, throughput, and error catalog). Telemetry is off by default — no exporters are registered and there is no overhead until you enable it.

Configure it under the Telemetry section:

{
  "Telemetry": {
    "Tracing": { "Enabled": true, "SampleRatio": 1.0, "Console": false },
    "Metrics": { "Enabled": true },
    "Otlp": { "Endpoint": "http://collector:4317" }
  }
}

Setting	Type	Default	Description
Telemetry:Tracing:Enabled	bool	false	Master switch for telemetry export.
Telemetry:Tracing:SampleRatio	double	1.0	Head-based trace sample ratio (1.0 = sample every trace). Applied through a parent-based sampler. Metrics are never sampled.
Telemetry:Tracing:Console	bool	false	Also emit to the console exporter — useful in development. Applies to both traces and metrics.
Telemetry:Metrics:Enabled	bool / null	null	Whether the metrics catalog is exported. null follows the tracing switch (enabling telemetry gives you both); set true or false to scope metrics independently.
Telemetry:Otlp:Endpoint	string	""	OTLP endpoint, for example http://collector:4317. When empty, an enabled setup exports to the console only.

How enablement resolves

• Telemetry turns on if Telemetry:Tracing:Enabled is true or the standard OTEL_EXPORTER_OTLP_ENDPOINT environment variable is set. Setting that environment variable both switches tracing on and supplies the endpoint when Otlp:Endpoint is empty.
• Metrics follow the tracing decision unless Telemetry:Metrics:Enabled is set explicitly.
• Exporter selection: if telemetry is enabled but no endpoint resolves, Zaris falls back to the console exporter (the local-development default). If an endpoint is set, the OTLP exporter is used — plus the console exporter as well when Tracing:Console is true.

Resource attributes

Every exported trace and metric carries these resource attributes, so you can filter by store and node in your backend:

Attribute	Value
service.name	clustron-zaris
service.instance.id	the node id
clustron.store	the cluster id (falls back to clustron)
clustron.node	the node id

tip

To wire Zaris into an existing stack, run an OpenTelemetry Collector and point Telemetry:Otlp:Endpoint (or OTEL_EXPORTER_OTLP_ENDPOINT) at it, then fan out to Prometheus, Grafana, Tempo, or Jaeger from the collector.

Telemetry environment variables

These can be set instead of, or alongside, the Telemetry configuration section:

Variable	Default	Effect
OTEL_EXPORTER_OTLP_ENDPOINT	unset	OTLP endpoint. Setting it also switches tracing on and supplies the endpoint when Telemetry:Otlp:Endpoint is empty.
OTEL_EXPORTER_OTLP_PROTOCOL	unset	OTLP protocol (for example grpc or http/protobuf).
ZARIS_TRACE	unset	1 enables verbose node trace logging at startup — independent of the Telemetry section, useful for one-off diagnostics.
CLUSTRON_TELEMETRY	enabled	Anonymous product-usage telemetry is sent unless this is set to false. This is separate from your own OpenTelemetry export above.

note

Anonymous usage telemetry is on by default. To opt out, set CLUSTRON_TELEMETRY=false on the node/host process.

Push metrics (legacy)

Separately from OpenTelemetry, a store can push a rolling metrics summary to an HTTP endpoint. This is the older push-based path and is distinct from the OTLP telemetry above — prefer OTLP for new deployments.

Setting	Type	Default	Description
pushMetrics.pushTargetUrl	string	none	Where to push the rolling metrics summary. Unset disables it.
pushMetrics.rollingWindowSeconds	int	120	Size of the rolling window.
pushMetrics.timeoutMilliseconds	int	60000	Push request timeout.

Next steps

• Observability — the metric instruments Zaris emits and what to watch.
• Monitoring — the live console and CLI views.
• Configuration reference — the complete store and client schema.