Troubleshooting

No spans are exported

Spans are only exported once telemetry.enabled (env TELEMETRY_ENABLED) is set and @quik/telemetry is registered in bootstrap. Without it, getTelemetry() resolves to QDefaultTelemetry, whose spans are true no-ops (startSpan() returns a span whose end() does nothing, and withSpan() just runs the callback).

Spans exported without a service name

Set telemetry.serviceName (env TELEMETRY_SERVICE_NAME); it is written to process.env.OTEL_SERVICE_NAME before the SDK starts. Leaving it empty exports spans under the OpenTelemetry SDK's own default.

Spans not reaching the collector

Confirm telemetry.exporter.otlp.endpoint (env TELEMETRY_OTLP_ENDPOINT) points at a reachable OTLP HTTP endpoint (e.g. https://collector:4318/v1/traces).

Logs not attached to spans

telemetry.logging.bridge must be enabled for TelemetryLogger to attach log records to the active span, and telemetry.logging.passthrough must also be enabled if you still want those logs written through the regular logger.

Common Errors

@quik/telemetry has no locale file of its own — there are no quik.errors.telemetry.* keys. Telemetry helpers (startSpan, endSpan, recordSpanError, setSpanAttribute, withSpan) are designed to degrade to no-ops rather than throw when telemetry is disabled or misconfigured.