{"record":{"id":"51b8ad093a81a022","repo":"caddyserver/caddy","slug":"tracerprovider-shutdown-w","errorCode":null,"errorMessage":"tracerProvider shutdown: %w","messagePattern":"tracerProvider shutdown: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"modules/caddyhttp/tracing/module.go","lineNumber":61,"sourceCode":"\t\tNew: func() caddy.Module { return new(Tracing) },\n\t}\n}\n\n// Provision implements caddy.Provisioner.\nfunc (ot *Tracing) Provision(ctx caddy.Context) error {\n\tot.logger = ctx.Logger()\n\n\tvar err error\n\tot.otel, err = newOpenTelemetryWrapper(ctx, ot.SpanName, ot.SpanAttributes)\n\n\treturn err\n}\n\n// Cleanup implements caddy.CleanerUpper and closes any idle connections. It\n// calls Shutdown method for a trace provider https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#shutdown.\nfunc (ot *Tracing) Cleanup() error {\n\tif err := ot.otel.cleanup(ot.logger); err != nil {\n\t\treturn fmt.Errorf(\"tracerProvider shutdown: %w\", err)\n\t}\n\treturn nil\n}\n\n// ServeHTTP implements caddyhttp.MiddlewareHandler.\nfunc (ot *Tracing) ServeHTTP(w http.ResponseWriter, r *http.Request, next caddyhttp.Handler) error {\n\treturn ot.otel.ServeHTTP(w, r, next)\n}\n\n// UnmarshalCaddyfile sets up the module from Caddyfile tokens. Syntax:\n//\n//\ttracing {\n//\t    [span <span_name>]\n//\t\t[span_attributes {\n//\t\t\tattr1 value1\n//\t\t\tattr2 value2\n//\t\t}]\n//\t}","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules/caddyhttp/tracing/module.go#L43-L79","documentation":"Returned by the tracing module's Cleanup (implements caddy.CleanerUpper) when shutting down the OpenTelemetry tracer provider fails during config unload or process exit. The %w wrapping preserves the underlying otel error for errors.Is/As inspection.","triggerScenarios":"Any config change/reload or shutdown where otel.shutdown() fails: e.g. the exporter's Shutdown returning an error because the remote OTLP endpoint connection is broken, or shutdown was already called (context canceled).","commonSituations":"Reloading Caddy while the tracing backend (Jaeger/Collector/Zipkin) is unreachable, exporters buffering spans that cannot flush on shutdown, or mismatched otel library versions in custom builds.","solutions":["Check the wrapped error text: 'context canceled' during rapid reloads is usually benign; connection refused means the endpoint is down","Ensure the OTLP endpoint (OTEL_EXPORTER_OTLP_ENDPOINT) is reachable and correct","Upgrade/align opentelemetry Go library versions in custom builds (go mod tidy)","For noisy shutdowns on reload, stabilize the tracing endpoint or accept the non-fatal cleanup error"],"exampleFix":"# before\nexport OTEL_EXPORTER_OTLP_ENDPOINT=http://tracing-down:4318  # host down on reload\n\n# after\nexport OTEL_EXPORTER_OTLP_ENDPOINT=http://tracing.internal:4318  # reachable endpoint","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep the OTLP endpoint highly available; cleanup errors usually stem from an unreachable exporter","Treat 'context canceled' during rapid reloads as benign noise; alert only on persistent failures","Pin compatible otel versions when building custom Caddy binaries"],"tags":["caddy","tracing","opentelemetry","shutdown"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}