diff --git a/opentelemetry-guidelines.md b/opentelemetry-guidelines.md index d340f51..88fb49b 100644 --- a/opentelemetry-guidelines.md +++ b/opentelemetry-guidelines.md @@ -1,18 +1,47 @@ # OpenTelemetry Guidelines -This document provides guidance for language instrumentation agents that use -OpAMP. +This document provides guidance for OpenTelemetry agents that use OpAMP. -## Scope +## Collector + +This guidance is intended for OpenTelemetry Collector. + +### Identifying Attributes + +The OpenTelemetry Collector SHOULD specify the following attributes in +`AgentDescription.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 + own telemetry. + +These values SHOULD match the values that the Collector uses in the Resource of its +own telemetry. + +### Non-identifying Attributes + +The following attributes SHOULD be included in `AgentDescription.non_identifying_attributes`: + +- `os.type`, `os.version` - to describe where the Collector runs. +- `host.\*` to describe the host the Collector runs on. +- `cloud.\*` to describe the cloud where the host is located. +- any other relevant Resource attributes that describe this Collector and the + environment it runs in. +- any user-defined attributes that the end user would like to associate with + this Collector. + +## SDKs 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 +### Identifying Attributes Language instrumentation agents MUST copy the following OpenTelemetry SDK `Resource` attributes into `AgentDescription.identifying_attributes`: @@ -24,7 +53,7 @@ Language instrumentation agents MUST copy the following OpenTelemetry SDK These identifying attributes MUST match the values that the agent uses in the Resource of its own telemetry. -## Non-identifying Attributes +### Non-identifying Attributes Language instrumentation agents SHOULD copy all other OpenTelemetry SDK `Resource` attributes into `AgentDescription.non_identifying_attributes`, diff --git a/specification.md b/specification.md index 21c242a..5eaa41d 100644 --- a/specification.md +++ b/specification.md @@ -1204,18 +1204,6 @@ 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: - -- 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 - own telemetry. - The Agent SHOULD also include these attributes in the Resource of its own telemetry. The combination of identifying attributes SHOULD be sufficient to uniquely identify the Agent's own telemetry in the destination system to which @@ -1226,9 +1214,9 @@ the Agent sends its own telemetry. Attributes that do not necessarily identify the Agent but help describe where it runs. -The following attributes SHOULD be included: +Here are some examples of attributes that may be a good fit for non-identifying attributes: -- os.type, os.version - to describe where the Agent runs. +- os.\* to describe where the Agent runs. - host.\* to describe the host the Agent runs on. - cloud.\* to describe the cloud where the host is located. - any other relevant Resource attributes that describe this Agent and the