diff --git a/.chloggen/sdk-component-shutdown-event.yaml b/.chloggen/sdk-component-shutdown-event.yaml new file mode 100644 index 0000000000..9559203cbe --- /dev/null +++ b/.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: diff --git a/docs/otel/README.md b/docs/otel/README.md index 209b40aebf..cfce5ee4bc 100644 --- a/docs/otel/README.md +++ b/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 diff --git a/docs/otel/sdk-events.md b/docs/otel/sdk-events.md new file mode 100644 index 0000000000..e3c9ac3237 --- /dev/null +++ b/docs/otel/sdk-events.md @@ -0,0 +1,151 @@ + + +# 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. + + + +- [Component lifecycle events](#component-lifecycle-events) + - [Event: `otel.sdk.component.shutdown`](#event-otelsdkcomponentshutdown) + + + +## Component lifecycle events + +### Event: `otel.sdk.component.shutdown` + + + + + + +**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 `/` 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, `` 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) | + + + + + +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 diff --git a/docs/otel/sdk-metrics.md b/docs/otel/sdk-metrics.md index 6d2b7594d5..14f5be92ea 100644 --- a/docs/otel/sdk-metrics.md +++ b/docs/otel/sdk-metrics.md @@ -164,6 +164,8 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | --- | --- | --- | | `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) | @@ -177,6 +179,7 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | `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) | @@ -230,6 +233,8 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | --- | --- | --- | | `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) | @@ -243,6 +248,7 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | `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) | @@ -334,6 +340,8 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | --- | --- | --- | | `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) | @@ -347,6 +355,7 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | `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) | @@ -407,6 +416,8 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | --- | --- | --- | | `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) | @@ -420,6 +431,7 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | `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) | @@ -519,6 +531,8 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | --- | --- | --- | | `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) | @@ -532,6 +546,7 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | `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) | @@ -604,6 +619,8 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | --- | --- | --- | | `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) | @@ -617,6 +634,7 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | `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) | @@ -670,6 +688,8 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | --- | --- | --- | | `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) | @@ -683,6 +703,7 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | `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) | @@ -775,6 +796,8 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | --- | --- | --- | | `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) | @@ -788,6 +811,7 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | `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) | @@ -848,6 +872,8 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | --- | --- | --- | | `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) | @@ -861,6 +887,7 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | `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) | @@ -960,6 +987,8 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | --- | --- | --- | | `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) | @@ -973,6 +1002,7 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | `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) | @@ -1035,6 +1065,8 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | --- | --- | --- | | `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) | @@ -1048,6 +1080,7 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | `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) | @@ -1147,6 +1180,8 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | --- | --- | --- | | `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) | @@ -1160,6 +1195,7 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | `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) | @@ -1253,6 +1289,8 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | --- | --- | --- | | `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) | @@ -1266,6 +1304,7 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | `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) | @@ -1372,6 +1411,8 @@ Semantic conventions for individual RPC frameworks SHOULD document what `rpc.res | --- | --- | --- | | `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) | @@ -1385,6 +1426,7 @@ Semantic conventions for individual RPC frameworks SHOULD document what `rpc.res | `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) | diff --git a/docs/registry/attributes/otel.md b/docs/registry/attributes/otel.md index 42b3cebd6a..287d1fb2ae 100644 --- a/docs/registry/attributes/otel.md +++ b/docs/registry/attributes/otel.md @@ -60,7 +60,8 @@ Attributes used for OpenTelemetry component self-monitoring | Key | Stability | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | | `otel.component.name` | ![Development](https://img.shields.io/badge/-development-blue) | 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` | ![Development](https://img.shields.io/badge/-development-blue) | string | A name identifying the type of the OpenTelemetry component. [2] | `batching_span_processor`; `com.example.MySpanExporter` | +| `otel.component.shutdown.duration` | ![Development](https://img.shields.io/badge/-development-blue) | double | The wall-clock elapsed time of a shutdown attempt, in seconds. [2] | `0.015`; `30.0` | +| `otel.component.type` | ![Development](https://img.shields.io/badge/-development-blue) | string | A name identifying the type of the OpenTelemetry component. [3] | `batching_span_processor`; `com.example.MySpanExporter` | **[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. @@ -76,7 +77,11 @@ With this implementation, for example the first Batching Span Processor would ha 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. +**[2] `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. + +**[3] `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. --- @@ -87,6 +92,8 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | --- | --- | --- | | `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) | @@ -100,6 +107,7 @@ E.g. for Java the fully qualified classname SHOULD be used in this case. | `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) | ## OTel Event Attributes @@ -110,9 +118,9 @@ Attributes used by non-OTLP exporters to represent OpenTelemetry Event's concept | Key | Stability | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | -| `otel.event.name` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | string | Identifies the class / type of event. [3] | `browser.mouse.click`; `device.app.lifecycle` | +| `otel.event.name` | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | string | Identifies the class / type of event. [4] | `browser.mouse.click`; `device.app.lifecycle` | -**[3] `otel.event.name`:** This attribute SHOULD be used by non-OTLP exporters when destination does not support `EventName` or equivalent field. This attribute MAY be used by applications using existing logging libraries so that it can be used to set the `EventName` field by Collector or SDK components. +**[4] `otel.event.name`:** This attribute SHOULD be used by non-OTLP exporters when destination does not support `EventName` or equivalent field. This attribute MAY be used by applications using existing logging libraries so that it can be used to set the `EventName` field by Collector or SDK components. ## OTel Scope Attributes diff --git a/model/otel/events.yaml b/model/otel/events.yaml new file mode 100644 index 0000000000..82f63093e9 --- /dev/null +++ b/model/otel/events.yaml @@ -0,0 +1,67 @@ +groups: + - id: event.otel.sdk.component.shutdown + type: event + name: otel.sdk.component.shutdown + stability: development + brief: > + Indicates that an OpenTelemetry SDK component's shutdown attempt has ended, + whether by completing successfully, failing, or timing out. + note: | + **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: + - ref: otel.component.type + requirement_level: required + brief: > + The provider type. + examples: ["logger_provider", "tracer_provider", "meter_provider"] + - ref: otel.component.name + requirement_level: required + - ref: error.type + requirement_level: + conditionally_required: if the shutdown was not successful. + brief: > + Describes the class of error that caused the shutdown to fail. + note: | + `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. | + examples: ["timeout", "failed"] + - ref: otel.component.shutdown.duration + requirement_level: recommended + brief: > + 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. diff --git a/model/otel/registry.yaml b/model/otel/registry.yaml index 35c3b465df..d791a98cc7 100644 --- a/model/otel/registry.yaml +++ b/model/otel/registry.yaml @@ -181,6 +181,21 @@ groups: brief: > Prometheus metric exporter over HTTP with the default text-based format stability: development + - id: logger_provider + value: "logger_provider" + brief: > + The builtin SDK LoggerProvider + stability: development + - id: tracer_provider + value: "tracer_provider" + brief: > + The builtin SDK TracerProvider + stability: development + - id: meter_provider + value: "meter_provider" + brief: > + The builtin SDK MeterProvider + stability: development stability: development brief: > A name identifying the type of the OpenTelemetry component. @@ -208,3 +223,13 @@ groups: 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. examples: ["otlp_grpc_span_exporter/0", "custom-name"] + - id: otel.component.shutdown.duration + type: double + stability: development + brief: > + The wall-clock elapsed time of a shutdown attempt, in seconds. + note: | + 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. + examples: [0.015, 30.0]