Reference semantic conventions for SDK self-observability metrics by cijothomas · Pull Request #5087 · open-telemetry/opentelemetry-specification

cijothomas · 2026-05-11T20:16:46Z

Adds an in-development Self-Observability.md document and SDK-level Self-observability sections in the Tracing and Logs and Metrics SDK specs that point to it. The Self-Observability document defers to the OpenTelemetry semantic conventions for SDK self-observability metric names, attributes, and values.

This is step 1 of defining self-observability as part of the spec itself; follow-ups can extend it (e.g., exporter metrics, reader metrics, self-logs, self-events) under the same umbrella.

Companion PR in semantic-conventions reserving the error.type values (queue_full, already_shutdown): open-telemetry/semantic-conventions#3710.

Resolves #5086.

cijothomas · 2026-05-12T15:51:36Z

Thanks for discussing this in SIG Call.
@jsuereth Agreed to point to the website instead of main commit.
@lmolkova I started with a dedicated doc and then scoped down to this approach to get some directional alignment. Given general support on direction, lets review this PR as-is, and I can take care of moving to a dedicated self-observability doc. (I am also eager to see it covering internal Events (log with name))

@tigrannajaryan The PR desc has a "note for reviewers" - Let me know if that address your concern about spec trying to list what sem-conv should be covering.

lmolkova

LGTM directionally with a small caveat on moving / linking it from current self-diagnostics section

dashpole

Do you want to cover the other SDK components (e.g. simple {signal} processors, or the trace SDK (spans started/live), or log sdk (logs created).

There are also the span/log/metric exporter metrics, which it wold be nice to have on the corresponding OTLP exporters.

cijothomas · 2026-05-15T05:08:58Z

Do you want to cover the other SDK components (e.g. simple {signal} processors, or the trace SDK (spans started/live), or log sdk (logs created).

There are also the span/log/metric exporter metrics, which it wold be nice to have on the corresponding OTLP exporters.

Great points — fully agree these all deserve coverage. I'd like to keep this PR scoped as a first step to lock in directional acceptance: spec treats self-observability as a first-class concern and points to semantic conventions as the source of truth for metric names, attributes, and values. Once this PR is merged, I can follow up with rest of the metrics.

…in CHANGELOG entries

cijothomas · 2026-06-01T23:40:40Z

@dashpole Given I have refactored significantly after your approval, could you re-review please?

pellared

How about also adding The Metrics SDK SHOULD support [SDK self-observability](../self-observability.md). for completeness?

Adds a new specification/self-observability.md document defining SDK self-observability at the spec level, and adds a one-line Self-observability section to the Tracing, Metrics, and Logs SDK specs pointing to it. Also references it from error-handling.md and the top-level README.

Co-authored-by: David Ashpole <dashpole@google.com>

…en-telemetry#5087) Adds an in-development Self-Observability.md document and SDK-level Self-observability sections in the Tracing and Logs SDK specs that point to it. The Self-Observability document defers to the OpenTelemetry semantic conventions for SDK self-observability metric names, attributes, and values. This is step 1 of defining self-observability as part of the spec itself; follow-ups can extend it (e.g., exporter metrics, reader metrics, self-logs, self-events) under the same umbrella. Companion PR in semantic-conventions reserving the `error.type` values (`queue_full`, `already_shutdown`): open-telemetry/semantic-conventions#3710. Resolves open-telemetry#5086. --------- Co-authored-by: David Ashpole <dashpole@google.com>

### Context - Clarify that environment variable propagation carriers normalize requested keys, carrier keys, and returned keys. ([open-telemetry#5102](open-telemetry#5102)) - Specify that environment variable propagation carriers only read and return normalized environment variable names. ([open-telemetry#5144](open-telemetry#5144)) - Specify that an empty environment variable propagation name is non-normalized and normalizes to `_`. ([open-telemetry#5163](open-telemetry#5163)) ### Profiles - Remove duplicate information from and extend Profiles documentation (README.md, pprof.md). ([open-telemetry#4932](open-telemetry#4932)) ### Entities - Add specification for communicating entity information as structured log events. ([open-telemetry#4836](open-telemetry#4836)) ### Common - Add an in-development [SDK self-observability](specification/self-observability.md) section, referenced from the Tracing, Metrics, and Logs SDK specs. ([open-telemetry#5087](open-telemetry#5087)) - Clarify non-OTLP representation guidance for nested `AnyValue` values in arrays and maps. ([open-telemetry#5053](open-telemetry#5053)) - Add in-development guidance recommending a JSON object as the string representation for an attribute in non-OTLP protocols. ([open-telemetry#5028](open-telemetry#5028)) - Add in-development guidance recommending a JSON object as the string representation for an attribute collection in non-OTLP protocols. ([open-telemetry#5110](open-telemetry#5110)) ### Compatibility - Deprecate OpenCensus compatibility requirements in the specification. ([open-telemetry#5138](open-telemetry#5138)) - Stabilize sections of Prometheus Metrics Exporter. - Clarify resource attributes configuration. ([open-telemetry#5084](open-telemetry#5084)) - Stabilize the conversion of OTLP Summaries into Prometheus Summaries. ([open-telemetry#5107](open-telemetry#5107)) - Stabilize client libs section. ([open-telemetry#5106](open-telemetry#5106)) - Stabilize Prometheus Metrics Exporter default aggregation configuration. ([open-telemetry#5113](open-telemetry#5113)) - Stabilize sections of Prometheus and OpenMetrics Compatibility. - Stabilize OpenTelemetry Histogram to Prometheus Histogram transformation. ([open-telemetry#5091](open-telemetry#5091)) - Add optional OpenTelemetry Histogram to Prometheus Native Histogram with Custom Buckets transformation. ([open-telemetry#5091](open-telemetry#5091)) ### SDK Configuration - Add link to declarative config IdGenerator type ([open-telemetry#5133](open-telemetry#5133)) ### OTEPs - Context-scoped Attributes. ([open-telemetry#4931](open-telemetry#4931)) --------- Co-authored-by: Reiley Yang <reyang@microsoft.com>

…ry#5135) Adds non-normative supplementary guidelines covering lifecycle ordering, avoiding telemetry-induced-telemetry loops, and stability handling for SDK self-observability. Towards open-telemetry#5128. Follow-up to open-telemetry#5087. --------- Co-authored-by: Robert Pająk <pellared@hotmail.com> Co-authored-by: Jack Berg <34418638+jack-berg@users.noreply.github.com>

…telemetry#5237) This adds a new `SDK Self-Observability` section to the spec compliance matrix, tracking implementation status of the SDK self-observability metrics across languages. Motivation: self-observability was recently recognized in the spec (open-telemetry#5135 supplementary guidelines, open-telemetry#5087 semconv reference), and the guidelines state self-observability should be treated "like any other SDK feature for stability." The compliance matrix is where per-language SDK feature status already lives, so it's the natural home for tracking this too. The section lists all 17 metrics defined in the [semantic conventions for SDK metrics](https://opentelemetry.io/docs/specs/semconv/otel/sdk-metrics/), one row per metric, grouped by signal (span / log / metric / shared). Per-metric granularity keeps the `+`/`-` values honest, since a language can implement a group only partially and each metric stabilizes independently. As the semantic conventions add more SDK self-observability metrics over time, this section is expected to grow with them. If it eventually becomes too large to sit comfortably inside the main compliance matrix, we can move it into a dedicated document and link to it from here. All cells start as `-`. Filling in actual per-language status is intentionally left to follow-up PRs so each SIG can update its own column. Generated with `make compliance-matrix` from the per-language YAML files.

cijothomas marked this pull request as ready for review May 11, 2026 20:17

cijothomas requested review from a team as code owners May 11, 2026 20:17

cijothomas force-pushed the sdk-self-observability-metrics-link branch from 52ce704 to 1221b00 Compare May 11, 2026 23:44

dashpole reviewed May 12, 2026

View reviewed changes

Comment thread specification/semantic-conventions.md Outdated

lmolkova reviewed May 12, 2026

View reviewed changes

Comment thread specification/semantic-conventions.md Outdated

Comment thread specification/semantic-conventions.md Outdated

cijothomas mentioned this pull request May 12, 2026

Define a self-observability Event for SDK component shutdown (starting with BatchSpanProcessor) open-telemetry/semantic-conventions#3718

Open

dashpole reviewed May 13, 2026

View reviewed changes

Comment thread specification/trace/sdk.md Outdated

dashpole approved these changes May 15, 2026

View reviewed changes

peschinskiy reviewed May 15, 2026

View reviewed changes

Comment thread specification/logs/sdk.md Outdated

cijothomas requested a review from lmolkova May 15, 2026 15:44

jack-berg reviewed May 15, 2026

View reviewed changes

Comment thread specification/logs/sdk.md Outdated

jack-berg assigned lmolkova May 20, 2026

cijothomas mentioned this pull request May 26, 2026

Reserve already_shutdown as error.type value for SDK processor processed metrics open-telemetry/semantic-conventions#3710

Merged

cijothomas added a commit to cijothomas/opentelemetry-specification that referenced this pull request May 26, 2026

Reference PR open-telemetry#5087 instead of issue open-telemetry#5086 …

935a891

…in CHANGELOG entries

pellared reviewed May 27, 2026

View reviewed changes

Comment thread specification/logs/sdk.md Outdated

trask approved these changes Jun 1, 2026

View reviewed changes

lmolkova approved these changes Jun 1, 2026

View reviewed changes

pellared approved these changes Jun 2, 2026

View reviewed changes

Comment thread specification/self-observability.md Outdated

pellared approved these changes Jun 2, 2026

View reviewed changes

reyang approved these changes Jun 2, 2026

View reviewed changes

reyang reviewed Jun 2, 2026

View reviewed changes

Comment thread CHANGELOG.md Outdated

carlosalberto approved these changes Jun 2, 2026

View reviewed changes

bogdandrutu approved these changes Jun 2, 2026

View reviewed changes

pellared reviewed Jun 2, 2026

View reviewed changes

Comment thread CHANGELOG.md Outdated

pellared requested review from jack-berg and peschinskiy June 2, 2026 15:41

dashpole approved these changes Jun 2, 2026

View reviewed changes

Comment thread specification/self-observability.md Outdated

cijothomas force-pushed the sdk-self-observability-metrics-link branch from 14fd15e to 146fa38 Compare June 2, 2026 15:53

Apply suggestion from @dashpole

03a9db5

Co-authored-by: David Ashpole <dashpole@google.com>

jack-berg approved these changes Jun 2, 2026

View reviewed changes

reyang enabled auto-merge June 2, 2026 16:13

cijothomas mentioned this pull request Jun 2, 2026

Post-Graduation Roadmap for OpenTelemetry open-telemetry/community#3452

Open

Merge branch 'main' into sdk-self-observability-metrics-link

22a704f

reyang added this pull request to the merge queue Jun 2, 2026

Merged via the queue into open-telemetry:main with commit 2daeb9b Jun 2, 2026
9 checks passed

cijothomas deleted the sdk-self-observability-metrics-link branch June 2, 2026 16:46

This was referenced Jun 2, 2026

Add supplementary guidelines for SDK self-observability #5128

Closed

Add supplementary guidelines for SDK self-observability #5135

Merged

cijothomas added this to OTel Clients Self Observability Jun 10, 2026

cijothomas moved this to Done in OTel Clients Self Observability Jun 10, 2026

carlosalberto mentioned this pull request Jun 18, 2026

Release 1.58.0 #5164

Merged

cijothomas mentioned this pull request Jul 29, 2026

chore: Add SDK self-observability section to compliance matrix #5237

Merged

Navigation Menu

Uh oh!

Reference semantic conventions for SDK self-observability metrics - #5087

Reference semantic conventions for SDK self-observability metrics#5087
reyang merged 3 commits into
open-telemetry:mainfrom
cijothomas:sdk-self-observability-metrics-link

cijothomas commented May 11, 2026 •

edited

Loading

Uh oh!

cijothomas commented May 12, 2026

Uh oh!

Uh oh!

lmolkova left a comment

Uh oh!

Uh oh!

Uh oh!

dashpole left a comment

Uh oh!

Uh oh!

cijothomas commented May 15, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cijothomas commented Jun 1, 2026

Uh oh!

pellared left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

10 participants

Uh oh!

Conversation

cijothomas commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cijothomas commented May 12, 2026

Uh oh!

Uh oh!

lmolkova left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

dashpole left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cijothomas commented May 15, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cijothomas commented Jun 1, 2026

Uh oh!

pellared left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

10 participants

cijothomas commented May 11, 2026 •

edited

Loading