Mapping OpenTelemetry Semantic Conventions to Service-entry Spans
Overview
Datadog uses service-entry spans throughout the platform for features such as Trace Metrics and the APM Trace Explorer. This convention is unique to Datadog, but can be mapped from the SpanKind attribute in OpenTelemetry by following the opt-in guide below.
Requirements
- OTel Collector Contrib v0.100.0 or greater
- Datadog Agent v7.53.0 or greater
Setup
Enable the config option based on your ingestion path:
The new service-entry span identification logic can be enabled by setting the traces::compute_top_level_by_span_kind config option to true in the Datadog exporter and Datadog connector. This config option needs to be enabled in both the exporter and connector if both components are being used.
The new service-entry span identification logic can be enabled by adding "enable_otlp_compute_top_level_by_span_kind" to apm_config.features in the Datadog Agent config.
Supported conventions
Trace Metrics are generated for service entry spans and measured spans. These span conventions are unique to Datadog, so OpenTelemetry spans are identified with the following mapping:
| OpenTelemetry Convention | Datadog Convention |
|---|
| Root span | Service entry span |
Server span (span.kind: server) | Service entry span |
Consumer span (span.kind: consumer) | Service entry span |
Client span (span.kind: client) | Measured span |
Producer span (span.kind: producer) | Measured span |
Internal span (span.kind: internal) | No trace metrics generated |
Migration
This new service-entry span identification logic may increase the number of spans that generate trace metrics, which may affect existing monitors that are based on trace metrics. Users who only have internal spans will see a decrease in trace metrics.
If you have existing monitors based on trace metrics, you can update them after upgrading since this change introduces more consistency in trace metrics. If you only have internal spans, update your instrumentation according to the above table to receive trace metrics and service-entry spans.
SpanKind is typically set when a span is created, but can also be updated by using the transform processor in the OpenTelemetry Collector to control the mapping above. For example, if trace metrics are desired for an internal span, the following configuration transforms an internal span with http.path: "/health" into a client span:
transform:
trace_statements:
- context: span
statements:
- set(kind.string, "Client") where kind.string == "Internal" and attributes["http.path"] == "/health"
Further reading
Additional helpful documentation, links, and articles:
