Skip to content

Add OpenTelemetry guidelines doc #312

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tigrannajaryan merged 2 commits into from
Apr 23, 2026
+41 −0
Merged

Add OpenTelemetry guidelines doc #312

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6d0591e
Add OpenTelemetry guidelines doc
breedx-splk Apr 7, 2026
6785f05
Update OpenTelemetry identity guidance
breedx-splk Apr 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ This repository contains Open Agent Management Protocol (OpAMP)
[specification](specification.md) and Protobuf definitions in [proto](proto) directory.

See [releases here](https://github.com/open-telemetry/opamp-spec/releases) and [changelog here](CHANGELOG.md).
Additional standalone guidance for instrumentation runtimes is in
[opentelemetry-guidelines.md](opentelemetry-guidelines.md).

## Contributing

Expand Down
39 changes: 39 additions & 0 deletions opentelemetry-guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# OpenTelemetry Guidelines

This document provides guidance for language instrumentation agents that use
OpAMP.
Comment on lines +3 to +4
Copy link
Copy Markdown
Member

@pellared pellared Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(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.

Copy link
Copy Markdown
Contributor Author

@breedx-splk breedx-splk Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


## Scope

This guidance is intended for OpenTelemetry language agents that run as part of an instrumented
application process. Examples include auto-instrumentation language agents and similar
instrumentation runtimes built with OpenTelemetry SDKs.

This guidance does not apply to standalone agents such as the OpenTelemetry
Collector.

## Identifying Attributes

Language instrumentation agents MUST copy the following OpenTelemetry SDK
`Resource` attributes into `AgentDescription.identifying_attributes`:

- `service.name`
- `service.instance.id`
Copy link
Copy Markdown
Member

@Kielek Kielek Apr 23, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Contributor Author

@breedx-splk breedx-splk Apr 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

- `service.namespace.name`, if present

These identifying attributes MUST match the values that the agent uses in the
Resource of its own telemetry.

## Non-identifying Attributes

Language instrumentation agents SHOULD copy all other OpenTelemetry SDK
`Resource` attributes into `AgentDescription.non_identifying_attributes`,
excluding those added to the identifying attributes (above).

## Rationale
Copy link
Copy Markdown

@evan-bradley evan-bradley Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


For language instrumentation agents, the `service.*` attributes listed above
define the identity that OpAMP uses to associate an agent with its telemetry.
Copying the remaining Resource attributes into
`AgentDescription.non_identifying_attributes` preserves useful descriptive
context without expanding the agent identity beyond those service attributes.