From 9a8390a161db1cab0f7e27f03111ff4bececf523 Mon Sep 17 00:00:00 2001 From: SylvainJuge <763082+SylvainJuge@users.noreply.github.com> Date: Tue, 4 Jun 2024 16:24:23 +0200 Subject: [PATCH] Merge internal otel distribution spec (#865) * fix typo * merge internal spec elements * Update specs/agents/otel-distribution.md Co-authored-by: Steve Gordon * Update specs/agents/otel-distribution.md Co-authored-by: Christos Kalkanis --------- Co-authored-by: Steve Gordon Co-authored-by: Christos Kalkanis --- specs/agents/mobile/README.md | 4 +-- specs/agents/otel-distribution.md | 47 ++++++++++++++++++++++++++++++- 2 files changed, 48 insertions(+), 3 deletions(-) diff --git a/specs/agents/mobile/README.md b/specs/agents/mobile/README.md index 7d136f5c..7fd53a94 100644 --- a/specs/agents/mobile/README.md +++ b/specs/agents/mobile/README.md @@ -7,7 +7,8 @@ The mobile specific docs can be found: * [iOS Agent](https://www.elastic.co/guide/en/apm/agent/swift/0.x/intro.html) * [Android Agent](https://www.elastic.co/guide/en/apm/agent/android/current/index.html) -## Open Telementry +## OpenTelemetry + The mobile agents are the first agents at Elastic to be built on top of Open-Telementry. A large portion of the mobile agents' functionality can be attributed to the [opentelementry-swift](https://github.com/open-telemetry/opentelemetry-swift) and [opentelementry-java](https://github.com/open-telemtry/opentelemetry-java) packages. @@ -16,7 +17,6 @@ However, the Elastic mobile agents don't set every attribute defined (many only ## Semantic Conventions and APM Server Mappings - ### Resource Attributes Here is a list of resource attributes that are relevant for our mobile agents: diff --git a/specs/agents/otel-distribution.md b/specs/agents/otel-distribution.md index e4c37d40..bf26daea 100644 --- a/specs/agents/otel-distribution.md +++ b/specs/agents/otel-distribution.md @@ -36,6 +36,51 @@ When introducing new features, the decision between starting with platform-speci For simplicity the configuration in this specification will use the "environment variable" syntax, some platforms like Java might also support other ways to configure. +## Identification + +### User Agent headers + +Per the [OpenTelemetry Specification](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#user-agent), OpenTelemetry SDKs are expected to send a `User-Agent` header when exporting data to a backend. At a minimum, this header SHOULD identify the exporter, the language of its implementation, and the version of the exporter. + +Elastic distributions SHOULD configure a customized `User-Agent` header when possible[^1]. +This allows data exported from a vanilla SDK and an Elastic distribution to be easily distinguished. + +[^1]: Some OpenTelemetry SDKs (e.g. .NET) do not provide a mechanism to modify the `User-Agent` header. In this case, we accept their default. + +To conform with [RFC7231](https://datatracker.ietf.org/doc/html/rfc7231#section-5.5.3), the existing SDK `User-Agent` should be preceded by a product identifier and version for the Elastic distribution. + +``` +/ +``` + +For example, in the .NET distribution, the `User-Agent` header would be configured as follows: + +``` +elastic-otel-dotnet/1.0.0 OTel-OTLP-Exporter-Dotnet/1.6.0 +``` + +### Telemetry resource attributes + +Per the [semantic conventions](https://opentelemetry.io/docs/specs/semconv/resource/#telemetry-sdk), SDKs are expected to include the following resource attributes on captured signals. These are used to identify the SDK where the data was captured and should not be modified. + +- `telemetry.sdk.name` +- `telemetry.sdk.version` +- `telemetry.sdk.language` + +In the above attributes, the name and version should be the OTel SDK name and version. +The language should be the primary language that the SDK is intended for. +It is expected that the OpenTelemetry SDK sets these values. +Our distros should set them, only if the SDK code does not do so automatically. + +Intake currently reads these attributes and uses them to populate the `agent.Name` and `agent.Version` fields. + +The semantic conventions also [define two experimental attributes](https://opentelemetry.io/docs/specs/semconv/resource/#telemetry-sdk-experimental) to identify the distribution: + +- `telemetry.distro.name`: must be set to `elastic` +- `telemetry.distro.version`: must reflect the distribution version + +Distributions SHOULD set these attributes with appropriate values. + ## Features ### Inferred spans @@ -79,4 +124,4 @@ Implementation is currently platform specific: Supported platforms: [Java](https://github.com/elastic/elastic-otel-java/tree/main/universal-profiling-integration) -For the configuration options see [this section](universal-profiling-integration.md#configuration-options). \ No newline at end of file +For the configuration options see [this section](universal-profiling-integration.md#configuration-options).