# Datadog Resolves Evolving OpenTelemetry Semantics at Query Time

> Datadog's Semantic Core knowledge graph encodes conditional equivalences between Datadog and OpenTelemetry telemetry, letting queries span convention versions without rewriting stored data.

- Publication: Thoai Dispatch
- Canonical URL: https://vokythoai.dev/article/datadog-semantic-core-opentelemetry-query-time
- Section: News
- Author: Datadog Engineering
- Published: 2026-11-20
- Tags: opentelemetry, observability, datadog, semantic-conventions, knowledge-graph, query-engine, telemetry, metrics

OpenTelemetry (OTel) provides a common vocabulary for observability data through its semantic conventions, but that vocabulary keeps changing. When OpenTelemetry stabilized its HTTP semantic conventions, the `http.method` attribute became `http.request.method`. Organizations may run services instrumented with different convention versions alongside services using Datadog-native conventions, so queries must work across all representations. In a [Datadog Engineering post](https://www.datadoghq.com/blog/engineering/semantic-translation-otel/), the company explains how it resolves these equivalences at query time using a knowledge graph called the Semantic Core.

## Why it matters

Supporting mixed instrumentation is not a one-time migration. Datadog-native and OTel-instrumented services can coexist indefinitely, and OTel services can emit data with different semantic convention versions at the same time. The query layer must resolve equivalent semantics across all of them so products and users do not have to account for every physical name. A flat mapping table such as `http.method` to `http.request.method` handles direct substitutions, but Datadog says its requirements go beyond one-to-one mappings. Customers do not upgrade instrumentation in lockstep, so a table that maps only the current OTel name silently breaks for services still on the old convention.

## Technical details

In the Semantic Core, metrics are nodes carrying metadata such as type or units. Tags associated with those metrics are their own nodes, connected to the metrics they appear in. Equivalences are edges: between metric nodes to express that two metrics represent the same concept, and between tag nodes to express that two tag names refer to the same thing. An edge can also describe the conditions under which an equivalence holds. Deprecation edges connect earlier metric names to their replacements, while equivalence edges connect corresponding Datadog and OTel metrics. A deprecated-to-current edge makes the deprecated name transitively queryable without enumerating every cross-vocabulary pair.

Datadog notes that equivalences carry correctness conditions beyond names. For example, `system.cpu.utilization` (OTel) and `system.cpu.user` (Datadog) can both represent user-space CPU utilization, but treating them as equivalent requires a `state:user` tag filter and a scaling factor. The OTel metric reports a ratio in the range [0,1], while the Datadog metric reports a percentage in the range [0,100]. A name-only mapping misses both and produces silently wrong results.

Metric types add another layer. `http.server.request.duration` (OTel histogram) and `trace.web.request.duration` (Datadog distribution) represent the same concept but in different metric types. The equivalence holds for percentile queries but breaks for raw count or sum aggregations where bucket structures diverge. The graph's edge metadata encodes these conditions instead of treating every mapping as universally interchangeable. A single OTel metric can map to multiple Datadog metrics based on tag filters and unit transformations.

The Semantic Core produces a precomputed equivalence configuration consumed by the query layer, so equivalences are available when Datadog executes a query without requiring a graph lookup for every request. Datadog also validates the mappings against real telemetry data.

## What to watch

For teams running mixed instrumentation, the post highlights that semantic translation is a query-time concern rather than a storage migration. Datadog's approach keeps stored data unchanged and resolves equivalent telemetry transparently. The engineering takeaway is that name-only mapping tables are insufficient when units, metric types, tag filters, and convention versions vary. Encoding provenance and validity conditions in a graph, then precomputing a configuration for query execution, is the pattern Datadog describes. Teams building their own translation layers should expect equivalence to depend on the operation being performed, not just on the metric names.

## Sources

- [Datadog Engineering](https://www.datadoghq.com/blog/engineering/semantic-translation-otel/) (2026-11-19)
