Logging

Configuration

Sockudo installs its logging subscriber once at startup, so early boot diagnostics are visible. After configuration files and environment overrides are resolved, the filter and formatting settings are reloaded once. Output format is selected at process startup and cannot be changed by configuration.

Filter precedence is RUST_LOG, then the mode-specific override, then the built-in default. Source location (file and line) is included when debug = true. The [logging] config section controls include_target and colors_enabled after configuration loads.

JSON output

With LOG_OUTPUT_FORMAT=json, each line is a JSON object. Application event attributes live under fields so they cannot collide with formatter metadata such as timestamp, level, and target. The current span is emitted as span; the redundant full span list is omitted.

{
  "timestamp": "2026-07-18T12:00:00.000Z",
  "level": "INFO",
  "target": "sockudo_adapter::handler",
  "span": { "name": "socket", "app_id": "my-app", "socket_id": "123.456" },
  "fields": { "message": "socket connected", "channel_count": 3 }
}

OpenTelemetry export

When [opentelemetry].enabled and logs_enabled are true, the same structured tracing events are also emitted as OpenTelemetry log records. OTLP export does not replace stdout/stderr logging and does not change LOG_OUTPUT_FORMAT. Log records created inside a sampled trace carry its trace and span context, allowing an OpenTelemetry backend to correlate logs with request, WebSocket, horizontal-fanout, webhook, and queue spans.

Explicit sockudo_telemetry instrumentation spans remain enabled while trace export is active, independently of the local RUST_LOG verbosity. This preserves distributed trace continuity without enabling debug or trace log events on stdout/stderr.

Sockudo supports the stable OpenTelemetry traces, metrics, and logs signals over OTLP gRPC, HTTP/protobuf, and HTTP/JSON. W3C traceparent/tracestate propagation and baggage are enabled by default when telemetry is active. OpenTelemetry profiles are not supported.

Export is asynchronous, bounded, and fail-open. Collector connection failures, exporter timeouts, or a full telemetry queue never make /live or /up fail and do not block normal request handling. Sockudo attempts a bounded flush during graceful shutdown. Configure collectors, protocols, sampling, and credentials with the OpenTelemetry environment variables.

Severity levels

Correlation fields

Filter and correlate events with these stable fields:

Production lifecycle events

The default info filter records socket connection, sign-in, subscription, explicit unsubscription, terminal disconnection (with cause), configuration loading, and final webhook and push outcomes. Message traffic, presence-member transitions, queue traffic, and retry internals remain at debug or trace. A scheduled webhook retry is a warn; permanent delivery failure is an error.

The optional Ably compatibility surface uses the same lifecycle policy. Its connection, attachment, detachment, recovery-source, and disconnection events carry protocol = "ably" plus the applicable app_id, connection_id, and channel fields.

Data safety

Logs may contain operational IDs, channel names, user IDs, and event names. Logs never contain app keys or secrets, signatures, tokens, authorization data, request or response bodies, message payloads, raw queries, webhook URLs, provider credentials, device tokens, or private keys. This applies at every level: enabling debug or trace never permits payload, credential, or token logging. The same rule applies to OpenTelemetry logs, span attributes, events, resource attributes, baggage, and exporter diagnostics. Store OTLP headers and client private keys outside the config file, and do not put secrets or user payloads in OTEL_RESOURCE_ATTRIBUTES or baggage.