Skip to content

Clarify what language agents should use for identity #310

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

Closed
breedx-splk wants to merge 2 commits into from
Closed

Clarify what language agents should use for identity #310

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2000173
clarify what language agents should use for identity
breedx-splk Apr 6, 2026
804f5d9
make markdown toc
breedx-splk Apr 6, 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
33 changes: 27 additions & 6 deletions specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,11 @@ Status: [Beta]
+ [Agent Status Compression](#agent-status-compression)
+ [AgentDescription Message](#agentdescription-message)
- [AgentDescription.identifying_attributes](#agentdescriptionidentifying_attributes)
* [Standalone Agents](#standalone-agents)
* [Language Instrumentation Agents](#language-instrumentation-agents)
- [AgentDescription.non_identifying_attributes](#agentdescriptionnon_identifying_attributes)
* [Standalone Agents](#standalone-agents-1)
* [Language Instrumentation Agents](#language-instrumentation-agents-1)
+ [ComponentHealth Message](#componenthealth-message)
- [ComponentHealth.healthy](#componenthealthhealthy)
- [ComponentHealth.start_time_unix_nano](#componenthealthstart_time_unix_nano)
Expand Down Expand Up @@ -1204,13 +1208,15 @@ Attributes that identify the Agent.
Keys/values are according to OpenTelemetry [resource semantic
conventions](https://opentelemetry.io/docs/specs/semconv/resource/).

For standalone running Agents (such as OpenTelemetry Collector) the following
attributes SHOULD be specified:
###### Standalone Agents
Copy link
Copy Markdown
Member

@tigrannajaryan tigrannajaryan Apr 7, 2026

Choose a reason for hiding this comment

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

@breedx-splk let's move this section and the new "Language Instrumentation Agents" section to a separate document. We can call it something like opentelemetry-guidelines.md and it will contain all considerations that are specific to Otel agents. The specification.md will contain generic protocol specification, which is 99% of the content right now (the only exception is this paragraph, so let's move it out).


- service.name should be set to the same value that the Agent uses in its own telemetry.
- service.namespace if it is used in the environment where the Agent runs.
- service.version should be set to version number of the Agent build.
- service.instance.id should be set. It may be set equal to the Agent's
The OpenTelemetry Collector and other standalone Agents SHOULD use the following
identifying attributes:

- `service.name` should be set to the same value that the Agent uses in its own telemetry.
- `service.namespace` if it is used in the environment where the Agent runs.
- `service.version` should be set to version number of the Agent build.
- `service.instance.id` should be set. It may be set equal to the Agent's
instance uid (equal to ServerToAgent.instance_uid field) or any other value
that uniquely identifies the Agent in combination with other attributes.
- any other attributes that are necessary for uniquely identifying the Agent's
Expand All @@ -1221,8 +1227,19 @@ 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.

###### Language Instrumentation Agents

Instrumentation agents use an OpenTelemetry SDK instance which includes a
Copy link
Copy Markdown

@RassK RassK Apr 7, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

why not also filter service.name, service.namespace, service.version, service.instance.id to identifying_attributes and everything else to nonidentifying_attributes ?

Copy link
Copy Markdown

@RassK RassK Apr 7, 2026

Choose a reason for hiding this comment

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

CC: @stevejgordon

Resource that identifies the source of telemetry. These agents SHOULD
simply copy all of the Resource attributes into the `identifying_attributes`.

Additional attributes MAY be included to supplement the existing
Resource if needed.

##### AgentDescription.non_identifying_attributes

###### Standalone Agents

Attributes that do not necessarily identify the Agent but help describe where it
runs.

Expand All @@ -1236,6 +1253,10 @@ The following attributes SHOULD be included:
- any user-defined attributes that the end user would like to associate with
this Agent.

###### Language Instrumentation Agents

Instrumentation agents SHOULD leave the `non_identifying_attributes` empty.

#### ComponentHealth Message

Status: [Beta]
Expand Down
Loading