Reference semantic conventions for SDK self-observability metrics

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))

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)

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.

specification/logs/sdk.md

@@ -43,6 +43,7 @@ weight: 3
     + [ForceFlush](#forceflush-2)
     + [Shutdown](#shutdown-1)
 - [Concurrency requirements](#concurrency-requirements)
+- [Self-observability](#self-observability)
 
 <!-- tocstop -->
 
@@ -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).

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)
 
 <!-- tocstop -->
@@ -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)

specification/self-observability.md

@@ -0,0 +1,23 @@
+# Self-Observability
+
+**Status**: [Development](document-status.md)
+
+OpenTelemetry SDKs MAY 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.

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)
 
 <!-- tocstop -->
 
@@ -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).