Dynatrace Operator version 1.10+ OneAgent version 1.333+ ActiveGate version 1.343+
This page describes the new tagging model for Latest Dynatrace with some capabilities still rolling out.
Dynatrace enriches telemetry from Kubernetes workloads with primary Grail fields and tags. You can use the same metadata for segments, pipeline routing, bucket assignment, Grail permissions, and cost allocation, consistently across logs, metrics, spans, events, and Smartscape entities.
If you operate Kubernetes workloads as an SRE or application owner, this page shows you how to make the labels and annotations you already maintain work for filtering, routing, and access control in Dynatrace. Data arrives in Dynatrace already tagged, with no post-processing rules required. The same metadata appears on every signal the workload emits.
For general guidance on primary Grail fields and tags, see Primary tags.
Choose one of the options below. Try each in order and stop at the first one that covers your use case.
All enrichment options require metadataEnrichment to be enabled in your DynaKube:
spec:metadataEnrichment:enabled: true
By default, enrichment applies to all namespaces.1 If you configure a namespaceSelector, only matching namespaces receive enrichment. Excluded namespaces won't have complete primary Grail fields or tags populated on their telemetry. For complete coverage, prefer omitting the selector or configuring it to match all monitored namespaces.
Except kube-*, openshift-*, and the Dynatrace Operator namespace. See Configure monitoring for namespaces and pods for details.
Dynatrace automatically populates k8s.cluster.name and k8s.namespace.name on all telemetry from Kubernetes workloads, with no configuration required. If filtering, routing, and access control at the cluster or namespace level cover your use case, no additional setup is needed.
If your namespaces already carry labels or annotations that represent the context you want, such as team ownership, environment, cost center, security boundary, use central configuration to promote them to primary Grail tags or fields. No changes to workload manifests are required.
Each central configuration rule selects a source, for example, a namespace label, a namespace annotation, or a static literal value, and a target, such as a primary field or a primary tag.
How the source value reaches telemetry depends on the rule type:
k8s.namespace.label.<key> or primary_tags.<key>. Primary tags are written on the edge, without requiring a separate OpenPipeline processing step. You can configure two rules for the same source if you want to populate both Kubernetes and primary Grail tag targets with the same value.Configuration changes to central rules can take up to 15 minutes to take effect. You might need to restart affected pods. Rules created before you deploy your DynaKube are picked up immediately.
To set up central configuration
For a full reference of form fields and available dimensions, see Configure central enrichment rules.
metadata.dynatrace.com annotationsIf your namespaces don't carry suitable existing labels or annotations, or if you need pod-level granularity that central configuration can't provide, add dedicated metadata.dynatrace.com/primary_tags.<key>:<value> annotations directly to your Kubernetes manifests to set primary Grail tags. The same convention also accepts the supported primary fields dt.security_context, dt.cost.costcenter, and dt.cost.product. Any other metadata.dynatrace.com/<key> annotation is ignored for enrichment on signals.
metadata:annotations:# Primary tags:metadata.dynatrace.com/primary_tags.team: paymentsmetadata.dynatrace.com/primary_tags.environment: production# Supported primary fields:metadata.dynatrace.com/dt.security_context: confidentialmetadata.dynatrace.com/dt.cost.costcenter: it_servicesmetadata.dynatrace.com/dt.cost.product: fin_app
You can place these annotations at two scopes:
Namespace apply to every workload and pod inside that namespace.
Use this when the team, environment, or security context is defined at the namespace boundary and is shared by everything that runs there.Pod (typically through the pod template of a Deployment, StatefulSet, or DaemonSet) apply only to that pod.
Use this when you need to override the namespace defaults for a specific workload, or when different workloads in the same namespace need different metadata.When the same key is set at both scopes, the pod-level value wins for that pod.
You can define additional resource attributes directly in your DynaKube. Dynatrace Operator propagates these attributes to all telemetry signals without requiring you to modify namespaces, workloads, or pods. This is useful when you want to attach a fixed tag to all signals from a cluster, such as a team identifier, at the DynaKube level.
Three DynaKube sections control which signals receive which attributes:
| Field | Scope |
|---|---|
| Applied to all signals: OneAgent injection, OTLP exporter injection, standalone log monitoring, and ActiveGate. |
| Applied to OneAgent signals only. Takes precedence over duplicate keys in |
| Applied to OTLP telemetry of configured exporters only. Takes precedence over duplicate keys in |
Attribute keys prefixed with primary_tags.* become primary Grail tags. The primary fields dt.security_context, dt.cost.costcenter, and dt.cost.product are also supported.
apiVersion: dynatrace.com/v1beta6kind: DynaKubemetadata:name: dynakubenamespace: dynatracespec:apiUrl: https://<environment-id>.live.dynatrace.com/apiresourceAttributes:primary_tags.team: "alpha"oneAgent:cloudNativeFullStack:additionalResourceAttributes:aws.account.id: "000000000000"primary_tags.team: "charly"namespaceSelector:matchLabels:my.app.com/oneagent: "true"otlpExporterConfiguration:additionalResourceAttributes:aws.account.id: "000000000000"primary_tags.team: "charly"namespaceSelector:matchLabels:my.app.com/otel: "true"signals:metrics: {}traces: {}logs: {}
Dynatrace Operator propagates the merged attributes as follows:
dt_node_metadata.properties for OneAgents, and to dt_metadata.properties, dt_metadata.json, and the metadata.dynatrace.com pod annotation for OneAgent injected pods.OTEL_RESOURCE_ATTRIBUTES and the metadata.dynatrace.com pod annotation for injected pods..spec.resourceAttributes directly. Mode-specific additionalResourceAttributes does not affect these components.When both OneAgent injection and OTLP exporter injection are active on the same pod, both write to the shared metadata.dynatrace.com JSON annotation. Having the same key defined in both sections will result in undefined behavior. You must use distinct keys across OneAgent and OTLP additionalResourceAttributes when both are active on the same pod to avoid unpredictable behavior.
For pod injection use cases (OneAgent injection and OTLP exporter injection), Dynatrace Operator propagates attributes as Kubernetes pod annotations in the form metadata.dynatrace.com/<key>. Kubernetes annotation key suffixes must consist of valid DNS label characters, so Dynatrace Operator sanitizes attribute keys by replacing any invalid characters before writing them to annotations.
Dynatrace Operator validates attribute keys and reports the following:
metadata.dynatrace.com/<key>.For the full parameter reference, see the DynaKube API reference.
If none of these options apply, derive or assign primary tags at ingest with OpenPipeline and the processing stage. Use this as a fallback for environments where source-side or central enrichment isn't possible.
When the same key is set at multiple levels, the most specific definition wins:
The following table shows where primary tags and the special fields (dt.security_context, dt.cost.costcenter, dt.cost.product) land, by enrichment option.
| Signal | Central configuration | Dedicated annotations (pod or namespace) |
|---|---|---|
OneAgent metrics 1 | ||
JMX/PMI metrics collected via OneAgent 1 | ||
Service metrics 1 | ||
Kubernetes platform metrics | ||
Kubernetes events | ||
Smartscape Kubernetes entities | ||
Logs collected by OneAgent log module 1 | ||
Logs collected by FluentBit | ||
Spans, metrics, and logs collected by the OpenTelemetry Collector | ||
OneAgent events 1 |
OneAgent-based enrichment requires the Cloud Native Full Stack or Application Monitoring deployment mode. Classic Full Stack is not supported.
Primary Grail fields and tags appear as top-level fields and can be queried with DQL.
fetch logs| filter k8s.namespace.name == "checkout" AND primary_tags.team == "payments"
fetch bizevents| filter dt.cost.costcenter == "it_services"| summarize sum(value), by: {dt.cost.product}
fetch logs| filter dt.security_context == "confidential"| filter k8s.cluster.name == "prod-eu-1"
The following checks apply to the central configuration setup described in Promote existing namespace labels or annotations.
Label, Annotation, or Literal, and that the source key exactly matches the key on the namespace.kubectl get namespace <name> -o yaml and inspect the metadata.labels and metadata.annotations sections.metadataEnrichment is allowed in your DynaKube.
If you specify a namespaceSelector, make sure it matches the namespace you're testing.kubectl get pod <pod-name> -o yaml on a pod in the namespace and look for annotations starting with metadata.dynatrace.com/.
Their presence means the metadata reached the pod.