Skip to content

Commit c79fca9

Browse files
tigrannajaryantigrannajaryan
committed
Add agent semantic conventions
Resolves open-telemetry#396 Contributes to open-telemetry/opamp-spec#131 We need a way to record more information about agents than is currently possible using existing semantic conventions. Otel Collector in particular today uses service.name,service.instance.id,service.version attributes to report its own telemetry. These are useful but not sufficient, particularly we are missing the information about which distribution of Otel Collector it is. agent.type/agent.version/agent.id conventions are also aligned with ECS: https://www.elastic.co/guide/en/ecs/current/ecs-agent.html With introduction of this conventions the following attributes change in Otel Collector's own telemetry output: service.name -> agent.type service.version -> agent.version service.instance.id -> agent.id agent.distro will be added as one more property, the equivalent of which did not exist in the past.
1 parent 4728f63 commit c79fca9

File tree

4 files changed

+101
-0
lines changed

4 files changed

+101
-0
lines changed

‎docs/attributes-registry/agent.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
<!--- Hugo front matter used to generate the website version of this page:
2+
--->
3+
4+
# Agent
5+
6+
## Agent Attributes
7+
8+
<!-- semconv registry.agent(omit_requirement_level) -->
9+
| Attribute | Type | Description | Examples | Stability |
10+
|---|---|---|---|---|
11+
| `agent.distro` | string | Agent distribution. [1] | `github.com/signalfx/splunk-otel-collector`; `github.com/aws-observability/aws-otel-collector` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
12+
| `agent.id` | string | Unique identifier of agent instance. [2] | `627cc493-f310-47de-96bd-71410b7dec09` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
13+
| `agent.type` | string | Agent type. [3] | `io.opentelemetry.collector`; `com.dynatrace.one_agent`; `com.newrelic.infra_agent` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
14+
| `agent.version` | string | The version string of the agent. The format is not defined by these conventions. | `2.0.0`; `a01dbef8a` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
15+
16+
**[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).
17+
18+
**[2]:** If a deterministic source for an id is not available it is recommended to use a UUID v7 value.
19+
20+
**[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.
21+
<!-- endsemconv -->

‎docs/resource/agent.md

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<!--- Hugo front matter used to generate the website version of this page:
2+
--->
3+
4+
# Agent
5+
6+
## Agent Attributes
7+
8+
<!-- semconv agent(full) -->
9+
| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
10+
|---|---|---|---|---|---|
11+
| [`agent.type`](../attributes-registry/agent.md) | string | Agent type. [1] | `io.opentelemetry.collector`; `com.dynatrace.one_agent`; `com.newrelic.infra_agent` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
12+
| [`agent.distro`](../attributes-registry/agent.md) | string | Agent distribution. [2] | `github.com/signalfx/splunk-otel-collector`; `github.com/aws-observability/aws-otel-collector` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
13+
| [`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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
14+
15+
**[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.
16+
17+
**[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).
18+
<!-- endsemconv -->

‎model/registry/agent.yaml

+51
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
groups:
2+
- id: registry.agent
3+
prefix: agent
4+
type: attribute_group
5+
brief: >
6+
An agent.
7+
attributes:
8+
- id: type
9+
type: string
10+
stability: experimental
11+
brief: >
12+
Agent type.
13+
examples: [io.opentelemetry.collector,com.dynatrace.one_agent,com.newrelic.infra_agent]
14+
note: >
15+
A string that uniquely identifies the agent type. A recommended way to choose
16+
a value is to pick a reverse FQDN of a domain that is under the control of the
17+
agent's author. Must remain unchanged between different versions of the same
18+
agent type.
19+
20+
- id: distro
21+
type: string
22+
stability: experimental
23+
brief: >
24+
Agent distribution.
25+
examples: [github.com/signalfx/splunk-otel-collector, github.com/aws-observability/aws-otel-collector]
26+
note: >
27+
Identifies the distribution of the agent. A number of
28+
distributions can belong to the same `agent.type`. For example OpenTelemetry
29+
Collector has multiple known distributions, e.g.
30+
github.com/signalfx/splunk-otel-collector,
31+
github.com/aws-observability/aws-otel-collector, etc.
32+
The value is typically a URL where the agent's source code is hosted
33+
(without the preceding http/https scheme). However other approaches for choosing
34+
`agent.distro` values are also valid (e.g. reverse FQDN).
35+
36+
- id: version
37+
type: string
38+
stability: experimental
39+
brief: >
40+
The version string of the agent. The format is not defined by these conventions.
41+
examples: ["2.0.0", "a01dbef8a"]
42+
43+
- id: id
44+
type: string
45+
stability: experimental
46+
brief: >
47+
Unique identifier of agent instance.
48+
examples: ["627cc493-f310-47de-96bd-71410b7dec09"]
49+
note: >
50+
If a deterministic source for an id is not available it is recommended to use
51+
a UUID v7 value.

‎model/resource/agent.yaml

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
groups:
2+
- id: agent
3+
prefix: agent
4+
type: resource
5+
brief: >
6+
An agent
7+
attributes:
8+
- ref: agent.type
9+
requirement_level: required
10+
- ref: agent.version
11+
- ref: agent.distro

0 commit comments

Comments
 (0)