Mapping OpenTelemetry Semantic Conventions to Service-entry Spans

This feature is in beta. If you have any feedback, contact Datadog support.


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.

Opting in to the feature

This feature requires OTel Collector Contrib v0.100.0 or greater and Datadog Agent v7.53.0 or greater. To opt into the public beta, enable the config option depending on the 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 ConventionDatadog Convention
Root spanService 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


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:

      - context: span
          - set(kind.string, "Client") where kind.string == "Internal" and attributes["http.path"] == "/health"

Further reading

Additional helpful documentation, links, and articles: