{"record":{"id":"98aa09cf8fe21a9e","repo":"jaegertracing/jaeger","slug":"failed-to-stop-the-adaptive-sampling-aggregator","errorCode":null,"errorMessage":"failed to stop the adaptive sampling aggregator : %w","messagePattern":"failed to stop the adaptive sampling aggregator : %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/jaeger/internal/processors/adaptivesampling/processor.go","lineNumber":62,"sourceCode":"\t\ttp.telset.Logger,\n\t\totelmetrics.NewFactory(tp.telset.MeterProvider),\n\t\tparts.DistLock,\n\t\tparts.SamplingStore,\n\t)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to create the adaptive sampling aggregator: %w\", err)\n\t}\n\n\tagg.Start()\n\ttp.aggregator = agg\n\n\treturn nil\n}\n\nfunc (tp *traceProcessor) close(context.Context) error {\n\tif tp.aggregator != nil {\n\t\tif err := tp.aggregator.Close(); err != nil {\n\t\t\treturn fmt.Errorf(\"failed to stop the adaptive sampling aggregator : %w\", err)\n\t\t}\n\t}\n\treturn nil\n}\n\nfunc (tp *traceProcessor) processTraces(_ context.Context, td ptrace.Traces) (ptrace.Traces, error) {\n\tbatches := v1adapter.V1BatchesFromTraces(td)\n\tfor _, batch := range batches {\n\t\tfor _, span := range batch.Spans {\n\t\t\tif span.Process == nil {\n\t\t\t\tspan.Process = batch.Process\n\t\t\t}\n\t\t\ttp.aggregator.HandleRootSpan(span)\n\t\t}\n\t}\n\treturn td, nil\n}\n","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/jaegertracing/jaeger/blob/806f4447841ecdb60519f408b004a599d515f437/cmd/jaeger/internal/processors/adaptivesampling/processor.go#L44-L80","documentation":"This error wraps failures from aggregator.Close() when the adaptive sampling trace processor shuts down. The aggregator must flush pending sampling statistics and release the distributed lock; if graceful shutdown fails, the close lifecycle hook wraps the underlying error so the collector reports which component failed to stop.","triggerScenarios":"Calling close (collector shutdown or test) while tp.aggregator is non-nil and aggregator.Close() returns an error — e.g. the distributed lock cannot be released or background workers fail to stop within the shutdown deadline.","commonSituations":"Collector shutdown with the sampling store unreachable; the dist-lock backend (etcd/oteld) down at shutdown time so the lock cannot be released; context/deadline expiring before the aggregator's background loop exits.","solutions":["Read the wrapped inner error to identify which shutdown step failed (lock release vs worker shutdown)","Ensure the distributed-lock backend is reachable during shutdown so the aggregator can release its lock","Give the collector a sufficient shutdown timeout so background sampling workers can exit","If it recurs, check the sampling store health; repeated Close failures usually indicate an unhealthy backend"],"exampleFix":"# before: too-short shutdown kills the aggregator mid-flush\n# after: allow time for graceful stop in collector config\nservice:\n  telemetry: ...\n# run collector with a longer shutdown grace period, e.g.\n# ensure dist-lock backend is up: docker compose up etcd","handlingStrategy":"try-catch","validationCode":"if tp.aggregator != nil {\n    // check backend health before shutdown to anticipate Close failures\n    if err := healthCheckSamplingStore(ctx); err != nil {\n        logger.Warn(\"sampling store unhealthy; Close may fail to release dist lock\")\n    }\n}","typeGuard":null,"tryCatchPattern":"if err := tp.close(ctx); err != nil {\n    logger.Error(\"failed to stop adaptive sampling aggregator\", log.Error(err))\n    // decide whether to abort shutdown or continue; inspect wrapped cause\n    return fmt.Errorf(\"processor shutdown failed: %w\", err)\n}","preventionTips":["Keep the dist-lock backend available during shutdown windows","Use generous collector shutdown timeouts","Monitor sampling store health to avoid Close-time failures","Handle nil aggregator (processor never started) before closing"],"tags":["go","otel-collector","adaptive-sampling","shutdown"],"backgroundTag":"component-shutdown-failed","analyzedSha":"806f4447841ecdb60519f408b004a599d515f437","analyzedAt":"2026-09-01T02:39:22.140Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}