Add otel.sdk.component.shutdown self-observability event

.chloggen/sdk-component-shutdown-event.yaml

@@ -0,0 +1,9 @@
+change_type: enhancement
+
+component: otel
+
+note: Add `otel.sdk.component.shutdown` self-observability event and supporting attributes (`otel.component.shutdown.result`, `otel.component.shutdown.duration`).
+
+issues: [3718]
+
+subtext:

docs/otel/README.md

@@ -10,6 +10,7 @@ This document defines semantic conventions for telemetry emitted by the OpenTele
 
 Semantic conventions are defined for the following signals:
 
+* [Events](sdk-events.md)
 * [Metrics](sdk-metrics.md)
 
 [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status

docs/otel/sdk-events.md

@@ -0,0 +1,151 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: SDK Events
+--->
+
+# Semantic conventions for OpenTelemetry SDK events
+
+**Status**: [Development][DocumentStatus]
+
+Self-observability events emitted by OpenTelemetry SDK components.
+
+These events complement SDK self-observability metrics by providing per-instance
+confirmation of lifecycle transitions, such as whether shutdown completed cleanly.
+
+> [!NOTE]
+> Events are in-development and not yet available in some languages. Check the [spec-compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix.md#logs) to see the implementation status in the corresponding language.
+
+<!-- START doctoc -->
+
+- [Component lifecycle events](#component-lifecycle-events)
+  - [Event: `otel.sdk.component.shutdown`](#event-otelsdkcomponentshutdown)
+
+<!-- END doctoc -->
+
+## Component lifecycle events
+
+### Event: `otel.sdk.component.shutdown`
+
+<!-- semconv event.otel.sdk.component.shutdown -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+
+**Status:** ![Development](https://img.shields.io/badge/-development-blue)
+
+The event name MUST be `otel.sdk.component.shutdown`.
+
+Indicates that an OpenTelemetry SDK component's shutdown attempt has ended, whether by completing successfully, failing, or timing out.
+
+**Applicability.**
+
+This event SHOULD be emitted by each SDK provider instance
+(`TracerProvider`, `LoggerProvider`, `MeterProvider`) when its shutdown
+operation completes.
+
+**Emission rules.**
+
+At most one `otel.sdk.component.shutdown` event is emitted per provider
+instance per process lifetime.
+
+If the process terminates without invoking the provider's shutdown
+(e.g. a crash, `SIGKILL`, container eviction, or immediate process
+termination), no event is expected. Consumers MUST NOT interpret the
+absence of this event as evidence of a clean shutdown.
+
+The event timestamp SHOULD reflect the time at which the provider fully
+completed the shutdown process, including shutting down all child
+components. Combined with the `otel.component.shutdown.duration`
+attribute, the start of the shutdown attempt can be reconstructed as
+`timestamp - duration`.
+
+**Severity.**
+
+Implementations MUST set the log record severity to `WARN`
+(`SeverityNumber` = `13`) when `error.type` is present, and to `INFO`
+(`SeverityNumber` = `9`) otherwise.
+
+**Attributes:**
+
+| Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
+| --- | --- | --- | --- | --- | --- |
+| [`otel.component.name`](/docs/registry/attributes/otel.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | A name uniquely identifying the instance of the OpenTelemetry component within its containing SDK instance. [1] | `otlp_grpc_span_exporter/0`; `custom-name` |
+| [`otel.component.type`](/docs/registry/attributes/otel.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The provider type. [2] | `logger_provider`; `tracer_provider`; `meter_provider` |
+| [`error.type`](/docs/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` if the shutdown was not successful. | string | Describes the class of error that caused the shutdown to fail. [3] | `timeout`; `failed` |
+| [`otel.component.shutdown.duration`](/docs/registry/attributes/otel.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | double | The wall-clock elapsed time of the shutdown attempt, in seconds. Combined with the event timestamp, this lets consumers compute when the shutdown attempt started. [4] | `0.015`; `30.0` |
+
+**[1] `otel.component.name`:** Implementations SHOULD ensure a low cardinality for this attribute, even across application or SDK restarts.
+E.g. implementations MUST NOT use UUIDs as values for this attribute.
+
+Implementations MAY achieve these goals by following a `<otel.component.type>/<instance-counter>` pattern, e.g. `batching_span_processor/0`.
+Hereby `otel.component.type` refers to the corresponding attribute value of the component.
+
+The value of `instance-counter` MAY be automatically assigned by the component and uniqueness within the enclosing SDK instance MUST be guaranteed.
+For example, `<instance-counter>` MAY be implemented by using a monotonically increasing counter (starting with `0`), which is incremented every time an
+instance of the given component type is started.
+
+With this implementation, for example the first Batching Span Processor would have `batching_span_processor/0`
+as `otel.component.name`, the second one `batching_span_processor/1` and so on.
+These values will therefore be reused in the case of an application restart.
+
+**[2] `otel.component.type`:** If none of the standardized values apply, implementations SHOULD use the language-defined name of the type.
+E.g. for Java the fully qualified classname SHOULD be used in this case.
+
+**[3] `error.type`:** `timeout` takes precedence over `failed` when both conditions are
+observed (e.g. the shutdown budget expired while a child component
+was still flushing).
+
+Documented values for this event:
+
+| Value | Description |
+| --- | --- |
+| `timeout` | The configured shutdown budget expired before all child components completed. |
+| `failed` | One or more child components reported failure within the time budget. |
+
+**[4] `otel.component.shutdown.duration`:** Measured from the moment the shutdown operation started to the moment
+it ended (whether by completing, failing, or timing out). MUST be a
+non-negative value expressed in seconds.
+
+---
+
+`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
+
+| Value | Description | Stability |
+| --- | --- | --- |
+| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) |
+
+---
+
+`otel.component.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
+
+| Value | Description | Stability |
+| --- | --- | --- |
+| `batching_log_processor` | The builtin SDK batching log record processor | ![Development](https://img.shields.io/badge/-development-blue) |
+| `batching_span_processor` | The builtin SDK batching span processor | ![Development](https://img.shields.io/badge/-development-blue) |
+| `logger_provider` | The builtin SDK LoggerProvider | ![Development](https://img.shields.io/badge/-development-blue) |
+| `meter_provider` | The builtin SDK MeterProvider | ![Development](https://img.shields.io/badge/-development-blue) |
+| `otlp_grpc_log_exporter` | OTLP log record exporter over gRPC with protobuf serialization | ![Development](https://img.shields.io/badge/-development-blue) |
+| `otlp_grpc_metric_exporter` | OTLP metric exporter over gRPC with protobuf serialization | ![Development](https://img.shields.io/badge/-development-blue) |
+| `otlp_grpc_span_exporter` | OTLP span exporter over gRPC with protobuf serialization | ![Development](https://img.shields.io/badge/-development-blue) |
+| `otlp_http_json_log_exporter` | OTLP log record exporter over HTTP with JSON serialization | ![Development](https://img.shields.io/badge/-development-blue) |
+| `otlp_http_json_metric_exporter` | OTLP metric exporter over HTTP with JSON serialization | ![Development](https://img.shields.io/badge/-development-blue) |
+| `otlp_http_json_span_exporter` | OTLP span exporter over HTTP with JSON serialization | ![Development](https://img.shields.io/badge/-development-blue) |
+| `otlp_http_log_exporter` | OTLP log record exporter over HTTP with protobuf serialization | ![Development](https://img.shields.io/badge/-development-blue) |
+| `otlp_http_metric_exporter` | OTLP metric exporter over HTTP with protobuf serialization | ![Development](https://img.shields.io/badge/-development-blue) |
+| `otlp_http_span_exporter` | OTLP span exporter over HTTP with protobuf serialization | ![Development](https://img.shields.io/badge/-development-blue) |
+| `periodic_metric_reader` | The builtin SDK periodically exporting metric reader | ![Development](https://img.shields.io/badge/-development-blue) |
+| `prometheus_http_text_metric_exporter` | Prometheus metric exporter over HTTP with the default text-based format | ![Development](https://img.shields.io/badge/-development-blue) |
+| `simple_log_processor` | The builtin SDK simple log record processor | ![Development](https://img.shields.io/badge/-development-blue) |
+| `simple_span_processor` | The builtin SDK simple span processor | ![Development](https://img.shields.io/badge/-development-blue) |
+| `tracer_provider` | The builtin SDK TracerProvider | ![Development](https://img.shields.io/badge/-development-blue) |
+| `zipkin_http_span_exporter` | Zipkin span exporter over HTTP | ![Development](https://img.shields.io/badge/-development-blue) |
+
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+The component being shut down is identified by the existing
+[`otel.component.*`](/docs/registry/attributes/otel.md#otel-component-attributes) attributes,
+not encoded in the event name. This keeps the event name stable and reusable
+as the set of emitting components grows.
+
+[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status