Define a self-observability Event for SDK component shutdown (starting with BatchSpanProcessor)

[cijothomas]

There is no standardized Event today for "an SDK component (e.g. BatchSpanProcessor) has shut down." Each SDK does its own thing:

• Rust (BatchLogProcessor): warn-level event via tracing if dropped > 0. Silent otherwise.
• .NET (BatchExportProcessor): always emits via EventSource — Warning if dropped > 0, Informational otherwise (two distinct event names).
• Java (BatchSpanProcessor): logs per-export-cycle when drops occurred; nothing at shutdown.
• Go (batch_span_processor.go): silent.

This is naturally event-shaped: it happens once at a specific moment, the payload is a one-shot record (outcome + final dropped count), and a metric can't really answer "did my pipeline drain cleanly at container shutdown?". A standardized Event (general semantics) lets every SDK emit the same well-known signal.

Starting with spans avoids the log self-feedback concern (a log event reporting log-pipeline drops would route through the failing pipeline). This is intended as the first of a series of self-observability Events; others (cardinality limit reached, runtime data-loss markers, lifecycle events) will be proposed once this lands.

Proposal

Event name: otel.sdk.component.shutdown

The component is identified via the existing otel.component.* attributes, not in the event name.

Attribute	Status	Notes
otel.component.type	existing	initial scope: batching_span_processor
otel.component.name	existing	e.g. batching_span_processor/0
outcome	new	success / failed / timed_out
dropped count	new	total items dropped over the component's lifetime

Severity: WARN if outcome != success or dropped > 0, INFO otherwise.

Body: not used (per Event guidelines).

Open questions

1. One event name with variable severity (above), or two event names like .NET (shutdown + shutdown_with_loss)?
2. Outcome: reuse otel.status_code (OK/ERROR) or new attribute that distinguishes timed_out?
3. Routing: the LogRecord can't safely flow through the user's LoggerProvider if it's also shutting down. Spec PR Reference semantic conventions for SDK self-observability metrics opentelemetry-specification#5087 is the natural home for this guidance.
4. Include exported_count and/or shutdown_duration as attributes?

Related

• Spec PR introducing self-observability doc: Reference semantic conventions for SDK self-observability metrics opentelemetry-specification#5087
• SDK self-observability metrics: https://opentelemetry.io/docs/specs/semconv/otel/sdk-metrics/

[Dipanshusinghh]

Hi @michaelklishin , I’d like to work on this if it’s available. The proposal and cross-SDK behavior comparison make sense, and I’d be interested in helping define the event semantics and keeping it aligned with existing self-observability conventions.

Please assign this to me if possible. Thanks!

[cijothomas]

Related follow-up surfaced in the spec community meeting (2026-06-02): Liudmila suggested defining a verbose startup configuration event — emitted once at SDK init time describing the resolved effective configuration (env vars read with sensitive values redacted, configured exporters/processors/readers, detected Resource attributes, etc.).

This is naturally a sibling to the shutdown event proposed here — both are one-shot lifecycle events that don't fit a metric shape, and both benefit from a common cross-SDK schema. Worth considering as a follow-up once the shutdown event lands, or framing the issue as "SDK lifecycle events (startup + shutdown)" if scope expansion is preferred.

The spec-side supplementary guidelines PR (open-telemetry/opentelemetry-specification#5135) intentionally does NOT prescribe the event schema and defers it here.

[cijothomas]

Hi @michaelklishin , I’d like to work on this if it’s available. The proposal and cross-SDK behavior comparison make sense, and I’d be interested in helping define the event semantics and keeping it aligned with existing self-observability conventions.

Please assign this to me if possible. Thanks!

Thanks for your interest. I am not a maintainer in this repo so I cannot assign this issue to you (or anyone)!

Meanwhile, please start reviewing the draft PR I opened for shutdown event. If you can work on the startup event , that'd be awesome.