Add Instrumentation Supplementary Guidelines by cijothomas · Pull Request #5191 · open-telemetry/opentelemetry-specification

cijothomas · 2026-07-04T05:12:35Z

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

dashpole · 2026-07-06T15:49:25Z

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 · 2026-07-06T17:00:11Z

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 · 2026-07-13T09:32:19Z

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 · 2026-07-13T20:06:39Z

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 · 2026-07-31T13:59:37Z

@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 · 2026-08-04T15:57:39Z

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 · 2026-08-11T20:14:25Z

Pull request dashboard status

Waiting on the author · refreshed 2026-10-02 18:23 UTC

Respond to 6 review items (e.g. link a commit, explain why not, ask a follow-up):

Inline threads: 1, 2, 3
Top-level threads: 4, 5, 6

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.
Should this be with reviewers? Comment /dashboard route:reviewers to route it to them.
Anything wrong — including the routing? Report it with what you expected; it helps us improve the dashboard.

cijothomas · 2026-08-19T00:18:06Z

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 · 2026-08-26T12:57:12Z

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

cijothomas · 2026-08-26T18:28:49Z

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.

Signed-off-by: cijothomas <cijo.thomas@gmail.com>

…ementary-guidelines Signed-off-by: cijothomas <cijo.thomas@gmail.com> # Conflicts: # CHANGELOG.md

github-actions · 2026-09-17T03:28:23Z

This PR was marked stale. It will be closed in 14 days without additional activity.

cijothomas · 2026-09-23T04:38:55Z

@dashpole Can you re-review and check my comment in #5191 (comment)?

jmacd · 2026-09-23T22:23:02Z

I agree with @cijothomas's suggestion that this is specification-adjacent material and not user-facing material.

I would approve open-telemetry/opentelemetry.io#10815 recommend link text like "for a more formal treatment".

jmacd · 2026-09-23T22:27:06Z

To address @dashpole's concerns, I think opentelemetry.io could use code-ownership to ensure specification owners are required to approve changes in e.g., content/en/docs/concepts/instrumentation/libraries.md.

svrnm · 2026-09-25T09:38:28Z

To address @dashpole's concerns, I think opentelemetry.io could use code-ownership to ensure specification owners are required to approve changes in e.g., content/en/docs/concepts/instrumentation/libraries.md.

Agreed, I would in general like to have spec-approvers/TC to code-own the whole "concepts" section as it is in big parts a "simplified" version of the spec.

opentelemetry-pr-dashboard · 2026-09-30T23:23:03Z

Hi @cijothomas — just a friendly reminder that this pull request is waiting on you. The dashboard status comment has the open items and is kept current.

Replying is enough to hand it off — answer, explain why no change is needed, or ask a follow-up. The dashboard routes it onward once nothing on the list is waiting on you.
To hand it back for any other reason, including the dashboard getting this wrong, comment /dashboard route:reviewers.

pellared · 2026-10-02T18:14:19Z

+The specification already requires instrumentation to depend only on the
+OpenTelemetry API, not the SDK (see [Overview](overview.md#sdk)).


nit

Suggested change

The specification already requires instrumentation to depend only on the

OpenTelemetry API, not the SDK (see [Overview](overview.md#sdk)).

The specification already requires instrumentation to depend on the

OpenTelemetry API, and not the SDK (see [Overview](overview.md#sdk)).

I am not sure if "only" would not be misleading

pellared · 2026-10-02T18:16:26Z

+* When the instrumentation targets a particular version of the OpenTelemetry
+  Semantic Conventions, it should set the scope `schema_url` to the
+  corresponding [Telemetry Schema](schemas/README.md) URL.
+* The scope name and version are part of the emitted telemetry's identity.


Isn't the schema_url also part of the identity?

pellared · 2026-10-02T18:21:07Z

+## Testing
+
+Instrumentation authors are encouraged to test the telemetry their
+instrumentation emits using OpenTelemetry's in-memory exporter, asserting on the


Suggested change

instrumentation emits using OpenTelemetry's in-memory exporter, asserting on the

instrumentation emits e.g. using OpenTelemetry's in-memory exporter, asserting on the

There are other ways. E.g one can use https://pkg.go.dev/go.opentelemetry.io/otel/log/logtest to not even depend on the SDK in the tests.

Add Instrumentation Supplementary Guidelines (open-telemetry#5148)

2306300

cijothomas force-pushed the instrumentation-supplementary-guidelines branch from c7585e8 to 2306300 Compare July 4, 2026 05:18

cijothomas marked this pull request as ready for review July 4, 2026 05:21

cijothomas requested a review from a team as a code owner July 4, 2026 05:21

cijothomas commented Jul 6, 2026

View reviewed changes

Comment thread specification/instrumentation-supplementary-guidelines.md

cijothomas mentioned this pull request Jul 13, 2026

Link Instrumentation Supplementary Guidelines from the libraries concept page open-telemetry/opentelemetry.io#10815

Draft

lmolkova assigned lmolkova and jmacd and unassigned lmolkova Jul 22, 2026

opentelemetry-pr-dashboard Bot mentioned this pull request Aug 11, 2026

Pull Request Dashboard #5264

Open

This comment has been minimized.

Sign in to view

carlosalberto reviewed Aug 26, 2026

View reviewed changes

Comment thread specification/instrumentation-supplementary-guidelines.md

cijothomas added 3 commits August 26, 2026 16:41

Add native instrumentation example to Instrumentation Scope section

b1c3e88

Signed-off-by: cijothomas <cijo.thomas@gmail.com>

Merge remote-tracking branch 'origin/main' into instrumentation-suppl…

55bf6a7

…ementary-guidelines Signed-off-by: cijothomas <cijo.thomas@gmail.com> # Conflicts: # CHANGELOG.md

Merge branch 'main' into instrumentation-supplementary-guidelines

678e9b6

github-actions Bot added the Stale label Sep 17, 2026

cijothomas added 2 commits September 22, 2026 21:39

Merge branch 'main' into instrumentation-supplementary-guidelines

b5c3e34

Merge branch 'main' into instrumentation-supplementary-guidelines

e088d00

jmacd approved these changes Sep 23, 2026

View reviewed changes

github-actions Bot removed the Stale label Sep 24, 2026

cijothomas mentioned this pull request Sep 29, 2026

Require specification approval for concepts changes open-telemetry/opentelemetry.io#11888

Open

Merge branch 'main' into instrumentation-supplementary-guidelines

42abd66

pellared reviewed Oct 2, 2026

View reviewed changes

		The specification already requires instrumentation to depend only on the
		OpenTelemetry API, not the SDK (see [Overview](overview.md#sdk)).

	instrumentation emits using OpenTelemetry's in-memory exporter, asserting on the
	instrumentation emits e.g. using OpenTelemetry's in-memory exporter, asserting on the

Conversation

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

Uh oh!

Uh oh!

dashpole commented Jul 6, 2026

Uh oh!

cijothomas commented Jul 6, 2026

Uh oh!

Uh oh!

svrnm commented Jul 13, 2026

Uh oh!

cijothomas commented Jul 13, 2026

Uh oh!

cijothomas commented Jul 31, 2026

Uh oh!

dashpole commented Aug 4, 2026

Uh oh!

opentelemetry-pr-dashboard Bot commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull request dashboard status

Uh oh!

This comment has been minimized.

cijothomas commented Aug 19, 2026

Uh oh!

carlosalberto commented Aug 26, 2026

Uh oh!

Uh oh!

cijothomas commented Aug 26, 2026

Uh oh!

github-actions Bot commented Sep 17, 2026

Uh oh!

cijothomas commented Sep 23, 2026

Uh oh!

jmacd commented Sep 23, 2026

Uh oh!

jmacd commented Sep 23, 2026

Uh oh!

svrnm commented Sep 25, 2026

Uh oh!

opentelemetry-pr-dashboard Bot commented Sep 30, 2026

Uh oh!

pellared Oct 2, 2026

Choose a reason for hiding this comment

Uh oh!

pellared Oct 2, 2026

Choose a reason for hiding this comment

Uh oh!

pellared Oct 2, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

cijothomas commented Jul 4, 2026 •

edited

Loading

opentelemetry-pr-dashboard Bot commented Aug 11, 2026 •

edited

Loading