Add OpenTelemetry guidelines doc by breedx-splk · Pull Request #312 · open-telemetry/opamp-spec

breedx-splk · 2026-04-07T17:01:54Z

This follows #310.

It creates a new document instead of polluting the general high level OpAMP spec with tedious details about actual behavior.

tigrannajaryan · 2026-04-07T17:04:14Z

@open-telemetry/specs-approvers @open-telemetry/technical-committee please review.

This is opinionated take on how Otel SDKs should identify themselves via OpAMP in a remotely managed system.

RassK · 2026-04-07T19:14:24Z

+## Identifying Attributes
+
+Language instrumentation agents SHOULD copy all attributes from the
+OpenTelemetry SDK `Resource` into `AgentDescription.identifying_attributes`.


#310 (comment)

I do not get the idea for a single exception here, while everything else follows a different pattern?
https://github.com/open-telemetry/opamp-spec/blob/main/specification.md#agentdescriptionidentifying_attributes

why should a os.version be in the identifying_attributes list while here it's said otherwise:
https://github.com/open-telemetry/opamp-spec/blob/main/specification.md#agentdescriptionnon_identifying_attributes

@tigrannajaryan can probably help clarify this, but I think the idea is that language agents and the Collector treat Resource and telemetry slightly differently. Notably, the Collector's Resource for its own internal/diagnostic telemetry is often different than the Resource(s) of the things it is handling telemetry for (like other agents or the operating system or whatever)...whereas the language agents use a Resource to identify the source of ALL telemetry it produces.

In the end it's "2 pipes taking to the same place" anyway, so server can rearrange however it needs - but the change itself will be a breaking change if there is a need for one.

I just wanted to be sure that the base hypothesis about what the resource contains is same. At least in .NET it contains tons of general classifiers like os.version, host.arch, process.runtime.name.

@tigrannajaryan said that identifying_attributes should form a guid but in the end every extra component makes that guid stronger (besides being a very dynamic guid) 🤷‍♂️

#310 (comment)

I do not get the idea for a single exception here, while everything else follows a different pattern? https://github.com/open-telemetry/opamp-spec/blob/main/specification.md#agentdescriptionidentifying_attributes

We should copy that section into this file too. Those are also OpenTelemetry guidelines, for the Collector.

why should a os.version be in the identifying_attributes list while here it's said otherwise: https://github.com/open-telemetry/opamp-spec/blob/main/specification.md#agentdescriptionnon_identifying_attributes

There is no contradiction here. os.version is not in Collector's Resource, thus we do not expect it to be in identifying_attributes. But since information about OS used it typically useful to agents the guidelines recommend including it as non_identifying_attributes.

I just wanted to be sure that the base hypothesis about what the resource contains is same. At least in .NET it contains tons of general classifiers like os.version, host.arch, process.runtime.name.

This is the unfortunate result of how we are forced to put everything into Resource which is just a single bag of attributes. We simply have no way to differentiate attributes that are important for identification vs ones that are useful to have but are not required for identification. The new Entity concept solves this problem by having this clear distinction between identifying and non-identifying attributes, which mirror OpAMP concepts precisely.

For now I think it is fine for simplicity to say we include all Resource attributes.

Thanks for confirming!

RassK

#310 (comment)
I do not get the idea for a single exception here, while everything else follows a different pattern? https://github.com/open-telemetry/opamp-spec/blob/main/specification.md#agentdescriptionidentifying_attributes

We should copy that section into this file too. Those are also OpenTelemetry guidelines, for the Collector.

With this minor change, it's seems good to go.

tigrannajaryan · 2026-04-08T21:30:21Z

I am going to keep this open for a few days to get more extensive feedback from the community. I will publicize in Slack.

pellared · 2026-04-13T07:30:11Z

+This document provides guidance for language instrumentation agents that use
+OpAMP.


(nit) Can we settle on using a single term? Previously we have

guidance for instrumentation runtimes

Personally, I am not a fan of using the "agent" term. I suggest "component" or "runtime" or "implementation" (I do not have any strong opinion). I think the sentence below is the only one that where using "agent" is fine (however, we could also use zero-code instrumentation to align with https://opentelemetry.io/)

Examples include auto-instrumentation language agents and similar
instrumentation runtimes built with OpenTelemetry SDKs.

What matters for me the most is having consistent terminology used in this PR.

It's indeed a nit, and I don't feel that strongly about it. With whatever term you go with, you'll have people wondering about the other term. Using both helps to suggest that both are valid, but whatever, I get it....and I agree that "agent" is criminally overloaded. Not sure which term is the preferred term of art anymore honestly....

tigrannajaryan · 2026-04-13T16:08:53Z

@dmitryax please take a look.

evan-bradley · 2026-04-14T16:19:30Z

+Language instrumentation agents SHOULD leave
+`AgentDescription.non_identifying_attributes` empty.
+
+## Rationale


Suggested change

## Rationale

### Rationale

Mostly a nit: not sure whether this section or the identifying attributes section would be better, but shouldn't this be nested under one of those two? I don't think this rationale necessarily applies to the whole document.

tigrannajaryan

All, I have been thinking about the suggestion @dmitryax made and I think it is a good one.

We can hard code the triplet (service.name, service.instance.id, service.namespace.name) to be the identifying attributes for Otel SDKs.

All other Resource attributes can go into non-identifying attributes. As Dmitrii said if you enable/disable detectors or the environment changes these other attributes can change, which is not desirable for identifying attributes.

This matches the 2 formal requirements OpAMP spec has for identifying attributes, quoting from the spec:

The Agent SHOULD also include these attributes in the Resource of its own telemetry.

Yes, these attributes will be in own telemetry (if SDK reports own telemetry).

The combination of identifying attributes SHOULD be sufficient to uniquely identify the Agent's own telemetry in the destination system to which the Agent sends its own telemetry.

True again, the uniqueness is guaranteed. We already guarantee that the triplet is globally unique.

This also nicely aligns conceptually with how the upcoming Entities think about identifying and non-identifying attributes. The triplet is precisely the identifying attributes of the Service Instance entity.

@breedx-splk I know we earlier agreed the full Resource is the right choice, but I think I was wrong, this is a better approach.

Blocking this to prevent merging for now until we discuss this option.

breedx-splk · 2026-04-21T16:55:02Z

I should point out that @RassK suggested essentially the same thing over here in the original PR that I closed: #310 (comment)

I honestly do not care much about this stuff, so I don't have a real opinion. I will change this PR to reflect the new guidance: service.name, service.instance.id, service.namespace.name into identifying, everything else from the resource into non-identifying. 👍🏻

breedx-splk · 2026-04-21T17:09:45Z

Ok, I did the thing. I wonder if omitting deployment.environment.name is an oversight....but I'm not sure. I thought that users used deployment.environment.name to segregate environments (like staging, pre-prod, prod, us-west, etc)...but really, the instance id is probably enough, so whatever. 🤷🏻

tigrannajaryan · 2026-04-21T21:51:06Z

Ok, I did the thing. I wonder if omitting deployment.environment.name is an oversight....but I'm not sure. I thought that users used deployment.environment.name to segregate environments (like staging, pre-prod, prod, us-west, etc)...but really, the instance id is probably enough, so whatever. 🤷🏻

Thanks.

Yes, we can still use deployment.environment.name, which will go into non-identifying attributes. I think this is fine, it will be available in the backend for e.g. supplying different configs to different environments, but it is not necessary for globally unique identification, so we don't need it in the identifying attributes.

tigrannajaryan · 2026-04-21T21:52:39Z

@andykellr @dashpole @jack-berg @RassK @Kielek this PR has changed substantially. Please take another look.

Changed as expected.

Kielek · 2026-04-23T04:35:21Z

+`Resource` attributes into `AgentDescription.identifying_attributes`:
+
+- `service.name`
+- `service.instance.id`


Is it intentional to be here?
If not provided manually, it is generated during startup process. At least in the OTel .NET Auto.
After the restart, it will provide new id.

I am pretty sure that it was common behavior in other technologies at the time of implementation.

Ref: https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/blob/1ad703dec2062ebc50cef55dd76c81b8e8c08b11/src/OpenTelemetry.AutoInstrumentation/Configurations/ResourceConfigurator.cs#L51-L55

I didn't suggest it, but I understood it to be intentional, yes.

Without it, you're just left with service.name and service.namespace, which is too ambiguous and doesn't serve to uniquely identify an agent instance.

Kielek

It should be also fine, with some comment related to service.instance.id

tigrannajaryan · 2026-04-23T18:16:09Z

Merging. If further refinements are needed, can be done in a future PR.

tigrannajaryan · 2026-04-23T18:26:48Z

Continuation which moves Otel Collector guidelines to the same doc: #318

Continuation of open-telemetry#312 This brings Otel Collector guidelines from specification.md to the opentelemetry-guidelines.md where we want all Otel-related guidelines to be.

Add OpenTelemetry guidelines doc

6d0591e

breedx-splk requested a review from a team as a code owner April 7, 2026 17:01

tigrannajaryan approved these changes Apr 7, 2026

View reviewed changes

tigrannajaryan requested review from andykellr and evan-bradley April 7, 2026 17:37

RassK reviewed Apr 7, 2026

View reviewed changes

Kielek approved these changes Apr 8, 2026

View reviewed changes

RassK approved these changes Apr 8, 2026

View reviewed changes

tigrannajaryan requested a review from jsuereth April 8, 2026 21:45

jack-berg approved these changes Apr 8, 2026

View reviewed changes

dashpole approved these changes Apr 9, 2026

View reviewed changes

pellared reviewed Apr 13, 2026

View reviewed changes

andykellr approved these changes Apr 14, 2026

View reviewed changes

evan-bradley reviewed Apr 14, 2026

View reviewed changes

dmitryax reviewed Apr 16, 2026

View reviewed changes

Comment thread opentelemetry-guidelines.md Outdated

tigrannajaryan previously requested changes Apr 17, 2026

View reviewed changes

Update OpenTelemetry identity guidance

6785f05

tigrannajaryan requested review from Kielek, RassK, andykellr, dashpole, dmitryax, jack-berg and pellared April 21, 2026 21:51

tigrannajaryan self-requested a review April 21, 2026 21:53

breedx-splk mentioned this pull request Apr 22, 2026

Introduce opamp data model for agents, starting with identity signalfx/gdi-specification#379

Merged

dmitryax approved these changes Apr 23, 2026

View reviewed changes

Kielek reviewed Apr 23, 2026

View reviewed changes

Kielek approved these changes Apr 23, 2026

View reviewed changes

andykellr approved these changes Apr 23, 2026

View reviewed changes

tigrannajaryan merged commit 5776668 into open-telemetry:main Apr 23, 2026
5 checks passed

tigrannajaryan mentioned this pull request Apr 23, 2026

Move Otel Collector guidelines from to opentelemetry-guidelines.md #318

Open

This was referenced Apr 23, 2026

Align OpAMP data model guidance with upstream signalfx/gdi-specification#387

Open

More opamp identity changes signalfx/splunk-otel-java#2788

Merged

dmitryax mentioned this pull request Apr 24, 2026

[extension/opampextension] Add agent_description.identifying_attributes config field open-telemetry/opentelemetry-collector-contrib#47481

Open

		This document provides guidance for language instrumentation agents that use
		OpAMP.

Conversation

breedx-splk commented Apr 7, 2026

Uh oh!

tigrannajaryan commented Apr 7, 2026

Uh oh!

RassK Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RassK left a comment

Choose a reason for hiding this comment

Uh oh!

tigrannajaryan commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tigrannajaryan commented Apr 13, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

tigrannajaryan left a comment

Choose a reason for hiding this comment

Uh oh!

breedx-splk commented Apr 21, 2026

Uh oh!

breedx-splk commented Apr 21, 2026

Uh oh!

tigrannajaryan commented Apr 21, 2026

Uh oh!

tigrannajaryan commented Apr 21, 2026

Uh oh!

Kielek Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kielek left a comment

Choose a reason for hiding this comment

Uh oh!

tigrannajaryan commented Apr 23, 2026

Uh oh!

Uh oh!

tigrannajaryan commented Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

10 participants

RassK Apr 7, 2026 •

edited

Loading

tigrannajaryan commented Apr 8, 2026 •

edited

Loading

Kielek Apr 23, 2026 •

edited

Loading

tigrannajaryan commented Apr 23, 2026 •

edited

Loading