Add agent semantic conventions #950
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| <!--- Hugo front matter used to generate the website version of this page: | ||
| ---> | ||
|
|
||
| # Agent | ||
|
|
||
| ## Agent Attributes | ||
|
|
||
| <!-- semconv registry.agent(omit_requirement_level) --> | ||
| | Attribute | Type | Description | Examples | Stability | | ||
| |---|---|---|---|---| | ||
| | `agent.distro` | string | Agent distribution. [1] | `github.com/signalfx/splunk-otel-collector`; `github.com/aws-observability/aws-otel-collector` |  | | ||
mx-psi marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| | `agent.id` | string | Unique identifier of agent instance. [2] | `627cc493-f310-47de-96bd-71410b7dec09` |  | | ||
|
There was a problem hiding this comment. What's the difference with There was a problem hiding this comment.
In the case when telemetry is being collected for the OTel Collector itself there's maybe no difference. For example, let's say the OTel collector collects metrics (or so) from an external service (let's say NGINX).
So with that we can differentiate the observer service from the observed service. @tigrannajaryan not sure if this PR had also this kind of scenario in mind? There was a problem hiding this comment.
It is the agent's instance id. Conceptually the same thing.
Preferably it should, but I don't want to mandate that in semconv, since some agents may not have persistence capability. We can add recommendations.
It was not a goal for me, but appears useful. When recording both of these attribute sets you essentially allow answering the question "who collected this telemetry?". My one concern would be that it bloats all telemetry coming from the Collector, so I am not sure if we should do it. |
||
| | `agent.type` | string | Agent type. [3] | `io.opentelemetry.collector`; `com.dynatrace.one_agent`; `com.newrelic.infra_agent` |  | | ||
| | `agent.version` | string | The version string of the agent. The format is not defined by these conventions. | `2.0.0`; `a01dbef8a` |  | | ||
mx-psi marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| **[1]:** Identifies the distribution of the agent. A number of distributions can belong to the same `agent.type`. For example OpenTelemetry Collector has multiple known distributions, e.g. github.com/signalfx/splunk-otel-collector, github.com/aws-observability/aws-otel-collector, etc. The value is typically a URL where the agent's source code is hosted (without the preceding http/https scheme). However other approaches for choosing `agent.distro` values are also valid (e.g. reverse FQDN). | ||
|
|
||
| **[2]:** If a deterministic source for an id is not available it is recommended to use a UUID v7 value. | ||
|
|
||
| **[3]:** A string that uniquely identifies the agent type. A recommended way to choose a value is to pick a reverse FQDN of a domain that is under the control of the agent's author. Must remain unchanged between different versions of the same agent type. | ||
| <!-- endsemconv --> | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,18 @@ | ||
| <!--- Hugo front matter used to generate the website version of this page: | ||
| ---> | ||
|
|
||
| # Agent | ||
|
|
||
| ## Agent Attributes | ||
|
|
||
| <!-- semconv agent(full) --> | ||
| | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | | ||
| |---|---|---|---|---|---| | ||
| | [`agent.type`](../attributes-registry/agent.md) | string | Agent type. [1] | `io.opentelemetry.collector`; `com.dynatrace.one_agent`; `com.newrelic.infra_agent` | `Required` |  | | ||
| | [`agent.distro`](../attributes-registry/agent.md) | string | Agent distribution. [2] | `github.com/signalfx/splunk-otel-collector`; `github.com/aws-observability/aws-otel-collector` | `Recommended` |  | | ||
| | [`agent.version`](../attributes-registry/agent.md) | string | The version string of the agent. The format is not defined by these conventions. | `2.0.0`; `a01dbef8a` | `Recommended` |  | | ||
|
|
||
| **[1]:** A string that uniquely identifies the agent type. A recommended way to choose a value is to pick a reverse FQDN of a domain that is under the control of the agent's author. Must remain unchanged between different versions of the same agent type. | ||
|
|
||
| **[2]:** Identifies the distribution of the agent. A number of distributions can belong to the same `agent.type`. For example OpenTelemetry Collector has multiple known distributions, e.g. github.com/signalfx/splunk-otel-collector, github.com/aws-observability/aws-otel-collector, etc. The value is typically a URL where the agent's source code is hosted (without the preceding http/https scheme). However other approaches for choosing `agent.distro` values are also valid (e.g. reverse FQDN). | ||
| <!-- endsemconv --> |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,51 @@ | ||
| groups: | ||
| - id: registry.agent | ||
| prefix: agent | ||
| type: attribute_group | ||
| brief: > | ||
| An agent. | ||
| attributes: | ||
| - id: type | ||
| type: string | ||
| stability: experimental | ||
| brief: > | ||
| Agent type. | ||
| examples: [io.opentelemetry.collector, com.dynatrace.one_agent, com.newrelic.infra_agent] | ||
| note: > | ||
| A string that uniquely identifies the agent type. A recommended way to choose | ||
| a value is to pick a reverse FQDN of a domain that is under the control of the | ||
| agent's author. Must remain unchanged between different versions of the same | ||
| agent type. | ||
|
|
||
| - id: distro | ||
| type: string | ||
| stability: experimental | ||
| brief: > | ||
| Agent distribution. | ||
| examples: [github.com/signalfx/splunk-otel-collector, github.com/aws-observability/aws-otel-collector] | ||
| note: > | ||
| Identifies the distribution of the agent. A number of | ||
| distributions can belong to the same `agent.type`. For example OpenTelemetry | ||
| Collector has multiple known distributions, e.g. | ||
| github.com/signalfx/splunk-otel-collector, | ||
| github.com/aws-observability/aws-otel-collector, etc. | ||
| The value is typically a URL where the agent's source code is hosted | ||
| (without the preceding http/https scheme). However other approaches for choosing | ||
| `agent.distro` values are also valid (e.g. reverse FQDN). | ||
|
|
||
| - id: version | ||
| type: string | ||
| stability: experimental | ||
| brief: > | ||
| The version string of the agent. The format is not defined by these conventions. | ||
| examples: ["2.0.0", "a01dbef8a"] | ||
|
|
||
| - id: id | ||
| type: string | ||
| stability: experimental | ||
| brief: > | ||
| Unique identifier of agent instance. | ||
| examples: ["627cc493-f310-47de-96bd-71410b7dec09"] | ||
| note: > | ||
| If a deterministic source for an id is not available it is recommended to use | ||
| a UUID v7 value. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| groups: | ||
| - id: agent | ||
| prefix: agent | ||
| type: resource | ||
| brief: > | ||
| An agent | ||
|
There was a problem hiding this comment. At the risk of being verbose, could we give a sentence or two to describe how we define "agent" in this context? The docs seem to define agent as a deployment pattern, but I think these conventions are agnostic of a deployment model and use a different definition for the term. I do see that this doesn't seem to appear anywhere in the readme output, so maybe there's no point. There was a problem hiding this comment. @evan-bradley I am not sure how much do we want to narrow down the definition of the agent to be honest. We could say "data collection agent" like OpAMP does, if that's useful. |
||
| attributes: | ||
| - ref: agent.type | ||
| requirement_level: required | ||
| - ref: agent.version | ||
| - ref: agent.distro | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Would be great to at least discuss what the value for this would be for core and contrib
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think we can use the github repo values, e.g.
github.com/open-telemetry/opentelemetry-collector-contribfor contrib. Do you think there are other, better options?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I am fine with those, in terms of implementation, would we add the distro value as a field to
component.BuildInfoor something similar?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should we restrict the number of examples ( columns)?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, I think so. That's where we put the short commands like "otelcol" today so we can add the corresponding distro string as another field of
BuildInfostruct.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@samiura I am not sure I understand. I have 2 examples for
agent.distrocurrently. Please clarify what you would like to restrict.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Not resolving to wait on @samiura's comment, but consider my comment resolved here :)