OpenTelemetry (OTel) gives observability data a common vocabulary through its semantic conventions, but the vocabulary continues to evolve. For example, when OpenTelemetry stabilized its HTTP semantic conventions, the http.method attribute became http.request.method. Because organizations may run services instrumented with different versions of the conventions alongside services that use Datadog-native conventions, queries need to work across all of these representations.
At first glance, supporting these conventions might seem like a straightforward mapping problem: http.method maps to http.request.method, for example. But semantic equivalence is more complicated than matching names. Two metrics can represent the same concept while using different units or metric types. An equivalence may apply only when a particular tag is present, and the same attribute can have different meanings depending on its context. A name-only mapping can produce incomplete or incorrect query results.
At Datadog, we represent these relationships in a knowledge graph called the Semantic Core. The graph captures equivalences between Datadog and OpenTelemetry metrics and span attributes, along with the conditions that determine when those equivalences are valid. Datadog applies this knowledge at query time, enabling queries to resolve equivalent telemetry data transparently across instrumentation approaches and convention versions without rewriting stored data or requiring users to know how that data was produced.
In this post, we’ll explain why semantic mappings require more than a flat translation table, how we represent conditional equivalences in the Semantic Core, and how we validate them against real telemetry data.
Supporting multiple semantic conventions at once
Supporting mixed instrumentation is not a one-time migration from one vocabulary to another. 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 has to resolve equivalent semantics across all of them so that products and users do not have to account for every physical name.
Why we needed a graph, not a flat mapping table
A flat mapping table, such as http.method → http.request.method, can handle direct substitutions, but our requirements go beyond one-to-one mappings. We need to represent transitive relationships, conditional equivalences, and metadata about when an equivalence is valid.
OpenTelemetry’s semantic conventions evolve, and customers don’t upgrade their instrumentation in lockstep. At any given time, some services may emit http.method (a deprecated pre-stabilization attribute), while others emit http.request.method (the current convention), and both need to resolve correctly against Datadog’s @http.method. A flat table that maps only the current OTel name silently breaks for services still on the old convention. In the graph, a deprecated → current edge makes the deprecated name transitively queryable without enumerating every cross-vocabulary pair explicitly. Flat mappings also can’t capture provenance: who defined an equivalence, which convention version it applies to, or whether it’s stable or experimental. Finally, they don’t scale to multiple vocabularies without multiplying the number of explicit mappings.
A knowledge graph gives us a richer data model for representing these relationships and their correctness conditions. In the Semantic Core, metrics are represented as nodes carrying metadata, such as type or units. The 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. The important distinction is that an edge can describe not only an equivalence but the conditions under which that equivalence holds.
When equivalent names aren’t enough
What makes equivalences harder to define than they look is that they’re not just name mappings—they carry correctness conditions.
Take system.cpu.utilization (OTel) and system.cpu.user (Datadog): Both can represent user-space CPU utilization, but treating them as equivalent requires a tag filter and a scaling factor. The state:user filter isolates user-space time in the OTel metric. The scaling factor accounts for the difference in units: The OTel metric reports a ratio in the range [0,1], while the Datadog metric reports a percentage in the range [0,100]. A naive 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 the bucket structures diverge. This means semantic equivalence can depend on the operation being performed, not just on the metrics themselves. The graph’s edge metadata gives us a place to encode those conditions instead of treating every mapping as universally interchangeable.
Representing equivalences in the graph is only one part of the problem: Those equivalences also need to be available when Datadog executes a query without requiring a graph lookup for every request. The Semantic Core produces a precomputed equivalence configuration consumed by the Semantics SDK. Query engines use this cached configuration to rewrite queries in memory rather than querying the graph during execution.
How query rewriting changes what customers see
When a query references an attribute name, the SDK looks up that name in its equivalence cache. If equivalences exist, the query is rewritten to capture all equivalent expressions.
One of the simplest rewrites is an OR expansion. A query for service.name:payments (OTel) expands to (service.name:payments OR service:payments), covering the Datadog-native equivalent. A metrics query for system.cpu.user (Datadog-native) expands to also cover system.cpu.utilization{state:user} (OTel), with appropriate aggregation semantics preserved.
These examples also show why the correctness conditions stored in the graph matter at execution time: Rewriting the metric name without carrying along the required tag filter or transformation would change the meaning of the query.
Importantly, the rewriting works in both directions. We don’t just expand the query to find data stored under a different name. We also normalize the results so they match the vocabulary of the query. If you query with Datadog-native names, you see results in Datadog-native format, even if the underlying data was ingested as OpenTelemetry. The translation is transparent to the caller.
How we validate semantic equivalences
Encoding a relationship in the graph doesn’t by itself prove that the relationship is correct. Because equivalences can depend on units, tags, metric types, and context, we also need to validate them against the behavior of real telemetry data.
Validation starts with the teams that own each domain. Domain experts validate the semantic definitions and define scenario-based tests that abstract away the underlying infrastructure, whether that means running a Datadog Agent, an OTel Collector, or both. Teams describe the expected equivalence behavior without having to manage the test environment directly. We then validate the equivalences in Datadog against real telemetry data.
Measuring correctness from inside the system isn’t enough. The Semantics SDK can report whether equivalences are being found and served from cache, but those signals describe the system’s own behavior, not whether the equivalences it’s applying are actually correct for real telemetry data. For that, we use an external validator.
The validator runs the same scenario across multiple configurations simultaneously: an OTel-only configuration, a Datadog-only configuration, and a hybrid configuration that combines OTel and Datadog components. Each scenario submits real telemetry data, runs the same queries using both OTel and Datadog-native vocabularies, and verifies that the results are consistent across all configurations.
The validation is end to end: Data submission, query execution, and result comparison all happen as a single unit. Any gap in the equivalences, such as a missing equivalence, an incorrect unit transformation, or a missing tag required for the equivalence to hold, produces a detectable result mismatch.
This lets us test the property we actually care about: Equivalent queries should produce equivalent results even when the underlying instrumentation and semantic conventions differ.
When a check fails, we notify the owning team, which acts on it. Because equivalence configurations are distributed dynamically to SDK instances without requiring a service restart, a bad equivalence can be corrected and rolled out quickly across the platform.
What’s next
As the number of semantic conventions and supported observability signals grows, the challenge shifts from defining individual equivalences to keeping a large, evolving set of equivalences correct.
Maintaining the graph is a federated effort: The engineering teams that own each product domain also own its semantic equivalences. Each team understands its domain’s telemetry data well enough to define the correctness conditions—which attributes map to one another, under what metric types, and in what contexts. Teams submit those definitions and their associated metadata to the platform team for incorporation into the graph, and new equivalence sets then propagate automatically to SDK instances.
Keeping those equivalences current as OTel evolves is a continuous process. The Semantic Core periodically scrapes the OTel semantic convention repositories and surfaces new or changed metric and tag definitions to the owning teams. When OTel stabilized its HTTP semantic conventions and renamed several attributes, for example, those changes were flagged automatically so the relevant teams could update their equivalences.
The tooling around the Semantic Core continues to evolve as the graph grows. Authoring equivalences at scale, managing ownership across integration namespaces, and validating changes across different instrumentation environments are now engineering problems in their own right.
Semantic translation as infrastructure
Semantic interoperability requires more than translating one attribute name into another. It requires representing what telemetry data means—and the conditions under which two representations can safely be treated as equivalent.
By representing those relationships explicitly in the Semantic Core and applying them at query time, we can separate the vocabulary used to query telemetry data from the names used when that data was produced. This lets different instrumentation approaches and semantic convention versions coexist without requiring every query to account for each representation individually.
As OpenTelemetry continues to evolve, we need to keep the Semantic Core current with new and changing conventions. That means evaluating whether metrics and attributes are actually equivalent, capturing conditions such as tags, units, and metric types, and validating those mappings against real telemetry data. Treating semantic translation as infrastructure gives us a consistent way to manage that work as conventions and instrumentation environments change.
If solving problems like semantic translation at scale sounds interesting, check out our open engineering roles at Datadog.











