Add Instrumentation Supplementary Guidelines

[cijothomas]

Fixes #5148

Companion PR for the website to ease discoverability: open-telemetry/opentelemetry.io#10815

[dashpole]

I reviewed the content, and think it is correct and useful. My main question is still whether this is the right place for it to live. I see this kind of document as user-facing, so I had imagined that it would be integrated into opentelemetry.io in a more discoverable way. But i'm open to other opinions.

[cijothomas]

I reviewed the content, and think it is correct and useful. My main question is still whether this is the right place for it to live. I see this kind of document as user-facing, so I had imagined that it would be integrated into opentelemetry.io in a more discoverable way. But i'm open to other opinions.

The main audience is instrumentation library authors. We do have supplementary guidelines for sdk authors, sdk extension point authors etc. So not a bad idea to keep it in spec repo. (And have a link from the docs website https://opentelemetry.io/docs/concepts/instrumentation/libraries/ )

[svrnm]

See my comment on the issue (#5148 (comment)): I am a big fan of having instrumentation guidelines, but we should decide if they sit in the spec, or if people would find them more easily in the docs.

[cijothomas]

See my comment on the issue (#5148 (comment)): I am a big fan of having instrumentation guidelines, but we should decide if they sit in the spec, or if people would find them more easily in the docs.

Would open-telemetry/opentelemetry.io#10815 be sufficient for the discoverability part?

[cijothomas]

@svrnm @dashpole Could you re-review and share your thoughts on keeping it in spec repo (this PR) and modify website docs as suggested here ?

[dashpole]

My preference is still to have the source of truth be the stand-alone, user-facing documentation on opentelemetry.io. The spec is the right place for content that is primarily for language implementation authors. This seems like content that is primarily for end users / instrumentation authors. I would expect the main, authoritative content to be on opentelemetry.io, and I would expect our supplementary guidelines to reference that, and add any details that are specific to instrumentation for sdks.

[opentelemetry-pr-dashboard]

Pull request dashboard status

Waiting on reviewers · refreshed 2026-08-27 19:15 UTC

Review the latest changes.

Status above doesn't look right?

• Just replied or pushed? Anything around or after the refresh time above may not be picked up yet — give it a few minutes.
• Anything look wrong? Report it with what you expected; it helps us improve the dashboard.

[cijothomas]

My preference is still to have the source of truth be the stand-alone, user-facing documentation on opentelemetry.io. The spec is the right place for content that is primarily for language implementation authors. This seems like content that is primarily for end users / instrumentation authors. I would expect the main, authoritative content to be on opentelemetry.io, and I would expect our supplementary guidelines to reference that, and add any details that are specific to instrumentation for sdks.

The audience is library owners who instrument natively or instrumentation library authors, not just end users. Spec's existing supplementary guidelines already serve them.
Eg: Metric supplementary guidelines - it says it's targeting instrumentation library authors.. Any end user who is writing instrumentation would benefit from the content there.
Logs supplementary guidelines - processor patterns for extension authors.
neither is normative, and both live in spec repo.

So, this PR is consistent with what the spec uses supplementary guidelines already for. I don't see any discoverability issue (open-telemetry/opentelemetry.io#10815 can help).

[carlosalberto]

We actually have a top level supplementary-guidelines directory. Maybe we should put this doc there?

[cijothomas]

We actually have a top level supplementary-guidelines directory. Maybe we should put this doc there?

I only see existing supplementary guidelines for each signal directory (logs/metrics) separately.
Or did you meant https://github.com/open-telemetry/opentelemetry-specification/tree/main/supplementary-guidelines which seem to be something like a leftover, and is not under specification directory.