Build1 publisherNot yet confirmed elsewhere2 min readPublished
OpenTelemetry's Kubernetes Attributes Processor v1.0.0 renames attributes that dashboards and alerts query
OpenTelemetry moved its Kubernetes Attributes Processor to v1.0.0 on stable semantic conventions that rename several attributes. Dashboards, alerts and queries built on the old label and image-tag names need updating as part of the upgrade.
The Engineer · Build desk
Drafted by a language model from the sources cited here and checked against its claim ledger before publication. How we use AISend a correction
What happened
- Under the stable conventions, container.image.tag becomes container.image.tags, while k8s.pod.labels and k8s.pod.annotations become k8s.pod.label and k8s.pod.annotation.
- Feature gates let the processor emit both the old and the new attribute names during a migration period.
- The 1.0 release gives API stability to organisations that redistribute the processor inside their own Collector distributions or binaries.
- Datadog's Collector distribution uses an infraattributes processor that pulls metadata from its Node Agent and Cluster Agent instead of each Collector querying the Kubernetes API.
Compiled by The EngineerSomething wrong?How this is made
Why it matters
- decision Upgrading becomes a schema migration for every consumer of the telemetry, so teams have to choose when to switch on dual emission and when to drop the old names.
- constraint Because one rename adds a plural and the others remove one, query and alert rewrites need an explicit per-attribute mapping, and a blanket find-and-replace will break something.
- cost Stable status leaves the per-pod metadata cache in place, so large clusters still pay for it in Collector memory unless filtering limits what gets collected.
- precedent Other Stable by Default components that emit convention-defined attributes face the same dependency: their output cannot freeze before the conventions it uses do.
The 1.0 tag covers two contracts. Redistributors get the API one [4]. The other covers output. According to InfoQ, the processor's metadata needs stable semantics if the telemetry it produces is to stay consistent over time [19]. Getting there took close coordination between the Collector SIG and the Kubernetes Semantic Conventions SIG [6]. The conventions reached release candidate in March and stable in June [13].
The output contract is where the upgrade cost sits. The processor discovers Kubernetes resources and attaches pod, namespace, node and workload metadata to logs, metrics and traces [2]. Any panel that groups by a pod label is reading a name this component wrote. The processor is stable for logs, metrics and traces, while profiles are still under development [3].
The renames run in both directions [20]. The pod, node and namespace label and annotation keys drop their plural, and the image tag gains one [7][8]. A sed one-liner that strips a trailing s fixes the labels and breaks the image tags. InfoQ lists dashboards, alerts, recording rules, queries, data pipelines and downstream integrations as places that may still use the old names [9].
The report does not name the feature gates or say which release stops emitting the old names. With dual emission available [10], I'd sequence the upgrade this way:
1. Enable both conventions before touching any consumer [10]. 2. Move dashboards, alerts, recording rules and queries to the new names while both are flowing [9]. 3. Update data pipelines and downstream integrations the same way [9]. 4. Turn off the old names once nothing reads them [10].
I think tying 1.0 to stable conventions is the right call. Shipping 1.0 on names that were still changing would have meant a second migration later. The formal graduation process also required telemetry stability, alongside code ownership, testing, benchmarking and documentation [12]. It is part of the Collector SIG's "Stable by Default" work, which began in late 2025 and used community feedback and Collector surveys to pick heavily used components [11].
The promotion does not change how the processor runs [14]. It still caches Kubernetes metadata in memory for the pods it monitors. The documentation flags limitations with host-networked pods and sidecar deployments [15]. The project has published CPU and memory benchmarks across Kubernetes workloads [16]. Those figures describe the project's test workloads. They would transfer to a production cluster with similar pod counts, metadata volume and filter settings [14].
Datadog argues that its agent-based approach, which keeps each Collector from querying the Kubernetes API directly, can reduce API load [17][18]. The upstream processor holds its own metadata cache in every Collector that runs it [14].
What to watch
- Collector release notes that name the Kubernetes feature gates and the release in which the old attribute names stop being emitted.
- Profiles support in the processor moving from development to stable, and whether it brings further attribute changes.
- Which heavily used component the Stable by Default effort graduates next, and whether its conventions have to stabilise first.