This documentation describes the new tagging model for Latest Dynatrace. Some capabilities are still rolling out. If you're currently using classic auto-tagging, see Classic vs. latest to understand how your existing setup maps to the new model.
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.
| Platform capability | How primary fields and tags help |
|---|---|
Data routing | Route data to specific pipelines based on |
Bucket assignment | Assign a target retention bucket based on |
Grail permissions | Derive security context from namespace boundaries or your own labels and annotations. |
Cost allocation | Track costs per team or product with |
Segments | Define segments based on primary fields and tags to filter data across Dynatrace apps. |
Alerting | Create targeted alerts and notifications based on primary fields and tags. |
Follow the steps below. Start with step 1, which uses primary Grail fields, and proceed to the next step only if the previous step doesn't meet your needs.
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 you need finer-grained context, such as team, application, business unit, or your own security boundaries, continue to step 2.
Central configuration is the recommended approach and will be made available mid-summer. Until it's shipped, use existing K8s metadata enrichment to enrich your workloads. The existing K8s metadata enrichment will be migrated to this new central configuration.
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 k8s.namespace.annotation.<key>.
A follow-up OpenPipeline processing step then copies the Kubernetes tag into the desired primary_tags.<key> or primary field.
This two-step flow keeps the original Kubernetes tag available for filtering and inspection while also lifting it into a primary tag.
After creating or modifying central configuration rules, allow up to 45 minutes for the changes to take effect, then restart the affected pods. Rules created before you deploy your DynaKube are picked up immediately.metadata.dynatrace.com annotations If 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.
If none of these options apply, derive or assign primary tags at ingest with OpenPipeline and the inline lookup processor. 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.*) land, by enrichment option.
| Signal | Central configuration | Dedicated annotations (pod or namespace) |
|---|---|---|
OneAgent metrics 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 Step 2.
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.metadata.dynatrace.com/ annotations with central configuration rules for the same key can lead to unexpected results because both write to the same target.