From 084df5d31b0f10a229ce28cedeab86f2515c85c5 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Wed, 17 Apr 2024 17:12:06 -0400 Subject: [PATCH] Add agent semantic conventions Resolves https://github.com/open-telemetry/semantic-conventions/issues/396 Contributes to https://github.com/open-telemetry/opamp-spec/issues/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. --- docs/attributes-registry/agent.md | 21 +++++++++++++ docs/resource/agent.md | 18 +++++++++++ model/registry/agent.yaml | 51 +++++++++++++++++++++++++++++++ model/resource/agent.yaml | 11 +++++++ 4 files changed, 101 insertions(+) create mode 100644 docs/attributes-registry/agent.md create mode 100644 docs/resource/agent.md create mode 100644 model/registry/agent.yaml create mode 100644 model/resource/agent.yaml diff --git a/docs/attributes-registry/agent.md b/docs/attributes-registry/agent.md new file mode 100644 index 0000000000..14de8c4a33 --- /dev/null +++ b/docs/attributes-registry/agent.md @@ -0,0 +1,21 @@ + + +# Agent + +## Agent Attributes + + +| Attribute | Type | Description | Examples | Stability | +|---|---|---|---|---| +| `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) | +| `agent.id` | string | Unique identifier of agent instance. [2] | `627cc493-f310-47de-96bd-71410b7dec09` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `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) | +| `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) | + +**[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. + diff --git a/docs/resource/agent.md b/docs/resource/agent.md new file mode 100644 index 0000000000..cf02659804 --- /dev/null +++ b/docs/resource/agent.md @@ -0,0 +1,18 @@ + + +# Agent + +## Agent Attributes + + +| 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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`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) | +| [`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) | + +**[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). + diff --git a/model/registry/agent.yaml b/model/registry/agent.yaml new file mode 100644 index 0000000000..3ddb301aaf --- /dev/null +++ b/model/registry/agent.yaml @@ -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. diff --git a/model/resource/agent.yaml b/model/resource/agent.yaml new file mode 100644 index 0000000000..c5ca67942c --- /dev/null +++ b/model/resource/agent.yaml @@ -0,0 +1,11 @@ +groups: + - id: agent + prefix: agent + type: resource + brief: > + An agent + attributes: + - ref: agent.type + requirement_level: required + - ref: agent.version + - ref: agent.distro