diff --git a/CHANGELOG.md b/CHANGELOG.md index e08ee35fdf0..38583803335 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -33,6 +33,9 @@ release. ### Common +- Add an in-development [SDK self-observability](specification/self-observability.md) + section, referenced from the Tracing, Metrics, and Logs SDK specs. + ([#5087](https://github.com/open-telemetry/opentelemetry-specification/pull/5087)) - Clarify non-OTLP representation guidance for nested `AnyValue` values in arrays and maps. ([#5053](https://github.com/open-telemetry/opentelemetry-specification/pull/5053)) diff --git a/specification/README.md b/specification/README.md index d37f22e457d..0e8c3560b8d 100644 --- a/specification/README.md +++ b/specification/README.md @@ -24,6 +24,7 @@ path_base_for_github_subdir: - [Library Guidelines](library-guidelines.md) - [Package/Library Layout](library-layout.md) - [General error handling guidelines](error-handling.md) + - [Self-Observability](self-observability.md) - [Performance](performance.md) - API Specification - [Context](context/README.md) diff --git a/specification/error-handling.md b/specification/error-handling.md index 7fd543043e9..659a47aa5bb 100644 --- a/specification/error-handling.md +++ b/specification/error-handling.md @@ -52,6 +52,9 @@ Another example may be a metric exposed by a `SpanProcessor` that describes the Whenever the library suppresses an error that would otherwise have been exposed to the user, the library SHOULD log the error using language-specific conventions. SDKs MAY expose callbacks to allow end users to handle self-diagnostics separately from application code. +See [Self-Observability](self-observability.md) for guidance on telemetry SDKs +emit about their own behavior, including SDK self-observability metrics. + ## Configuring Error Handlers SDK implementations MUST allow end users to change the library's default error handling behavior for relevant errors. diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index f9e0dd0b29f..fb8bb108173 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -43,6 +43,7 @@ weight: 3 + [ForceFlush](#forceflush-2) + [Shutdown](#shutdown-1) - [Concurrency requirements](#concurrency-requirements) +- [Self-observability](#self-observability) @@ -706,3 +707,9 @@ to be called concurrently. **LogRecordExporter** - `ForceFlush` and `Shutdown` MUST be safe to be called concurrently. + +## Self-observability + +**Status**: [Development](../document-status.md) + +The Logs SDK SHOULD support [SDK self-observability](../self-observability.md). diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 8204b3d1694..0f7a844446d 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -90,6 +90,7 @@ weight: 3 - [Numerical limits handling](#numerical-limits-handling) - [Compatibility requirements](#compatibility-requirements) - [Concurrency requirements](#concurrency-requirements) +- [Self-observability](#self-observability) - [References](#references) @@ -1946,6 +1947,12 @@ and `Shutdown` MUST be safe to be called concurrently. **MetricExporter** - `ForceFlush` and `Shutdown` MUST be safe to be called concurrently. +## Self-observability + +**Status**: [Development](../document-status.md) + +The Metrics SDK SHOULD support [SDK self-observability](../self-observability.md). + ## References - [OTEP0113 Integrate Exemplars with Metrics](../../oteps/metrics/0113-exemplars.md) diff --git a/specification/self-observability.md b/specification/self-observability.md new file mode 100644 index 00000000000..6ed57acb87b --- /dev/null +++ b/specification/self-observability.md @@ -0,0 +1,23 @@ +# Self-Observability + +**Status**: [Development](document-status.md) + +OpenTelemetry SDKs SHOULD emit self-observability ("internal") telemetry about +their own behavior (for example, metrics, logs, and other signals describing +the state of processors, exporters, and metric readers) to help operators +monitor the health of the OpenTelemetry pipeline itself. + +This is closely related to the +[self-diagnostics](error-handling.md#self-diagnostics) guidance in the error +handling document. + +## SDK Self-Observability Metrics + +The names, attributes, and values used for SDK self-observability metrics are +defined in the OpenTelemetry semantic conventions: +[SDK Metrics](https://opentelemetry.io/docs/specs/semconv/otel/sdk-metrics/). +SDKs that implement self-observability metrics SHOULD follow these conventions. + +Self-observability telemetry emitted during SDK startup and shutdown is +best-effort, because the SDK that records this telemetry may not yet be +initialized or may have already been shut down. diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 3643b8bba14..079e9e43404 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -83,6 +83,7 @@ weight: 3 - [Go SpanExporter Interface](#go-spanexporter-interface) - [Java SpanExporter Interface](#java-spanexporter-interface) - [Concurrency requirements](#concurrency-requirements) +- [Self-observability](#self-observability) @@ -1284,3 +1285,9 @@ concurrently. **Span Exporter** - `ForceFlush` and `Shutdown` MUST be safe to be called concurrently. + +## Self-observability + +**Status**: [Development](../document-status.md) + +The Tracing SDK SHOULD support [SDK self-observability](../self-observability.md).