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.
OneAgent enriches telemetry at the source with primary Grail fields and tags before sending logs, metrics, spans, events, and entities to Dynatrace. This gives you consistent metadata across all signal types for segments, pipeline routing, bucket assignment, and cost allocation. Host-level enrichment automatically propagates to all Smartscape nodes (hosts, processes, containers, networks, disks) and their signals.
For general guidance on primary Grail fields and tags, see Primary tags. For general OneAgent documentation, see Dynatrace OneAgent.
| Platform capability | How primary fields and tags help |
|---|---|
Data routing | Route data to specific pipelines based on |
Bucket assignment | Assign target retention bucket based on |
Grail permissions | Derive security context for data access control |
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 this hierarchy. Start with step 1 and only continue if the previous step doesn't cover your needs.
OneAgent automatically detects and enriches primary Grail fields like dt.host_group.id without any manual configuration. When OneAgent runs on Kubernetes (typically rolled out via the Dynatrace Operator), k8s.cluster.name and k8s.namespace.name are also populated automatically. If these built-in fields cover your filtering and access control needs, no additional setup is required.
Define primary fields and tags directly on the host or process so data is enriched before it leaves the host. You can apply tags at two scopes:
--set-host-tag, or at any later point on an existing installation with oneagentctl --set-host-tag.DT_TAGS environment variable. Use this when different processes on the same host need different metadata, or for serverless and managed container platforms where you can't configure the host itself (AWS Lambda and Azure Functions). When the same key is set at both scopes, the process-level value wins for that process.Dynatrace-OneAgent-Linux.sh --set-host-tag="primary_tags.environment=production" --set-host-tag="dt.security_context=confidential"
.\Dynatrace-OneAgent-Windows.exe --set-host-tag="primary_tags.environment=production" --set-host-tag="dt.security_context=confidential"
# Primary Grail fieldsoneagentctl --set-host-tag="dt.cost.costcenter=12345"oneagentctl --set-host-tag="dt.security_context=confidential"# Primary Grail tagsoneagentctl --set-host-tag="primary_tags.environment=production"oneagentctl --set-host-tag="primary_tags.team=bravo"
DT_TAGS="primary_tags.environment=production primary_tags.team=bravo primary_tags.application=payment-processing" java -jar checkout-service.jar
On serverless platforms, OneAgent can't auto-detect certain primary fields. Provide them via DT_TAGS at deploy time:
aws.account.id, aws.regionazure.subscription, azure.resource.group, azure.locationComing soon
If you can't reach every host to configure it individually, use central configuration in Dynatrace to apply primary tags and primary fields to all telemetry coming from hosts and processes.
Through central configuration, all signals emitted by the targeted host or process are enriched with the configured primary tags and primary fields. Enriching all data from a host based on a process or service property is not supported.
If none of these approaches work, use OpenPipeline and the inline lookup processor to derive or assign primary tags at ingest time. This should be a fallback for environments with constraints that prevent enrichment at an earlier stage.
When the same key is set at multiple scopes, the more specific definition wins:
DT_TAGS).oneagentctl).Host-level tags fill in any keys that the process didn't override.
| Resource | Enrichment level | Defined values | Enrichment result |
|---|---|---|---|
Host |
|
|
|
.NET Process |
|
|
|
Java Process |
|
|
|
Any other process | — | — |
|
The following table shows which enrichment methods are available in each environment.
Enrichment on Kubernetes requires OneAgent to be deployed via the Dynatrace Operator. Namespace labels and annotations can also be promoted through Kubernetes-side central configuration and reach OneAgent-emitted signals. For details, see Domain: Kubernetes.
Serverless workloads run only the OneAgent code module, so the installer, oneagentctl, and central configuration are not available. Central configuration would also introduce startup latency that's incompatible with these low-latency, volatile workloads. Enrich primary fields and tags through DT_TAGS when deploying the workload.
On mainframe, process-level enrichment is configured in the zremoteagentuserconfig.conf file, not via DT_TAGS.
Primary Grail fields and tags appear as top-level fields and can be queried with DQL:
fetch spans| filter primary_tags.team == "bravo" AND primary_tags.environment == "production"
fetch bizevents| filter dt.cost.costcenter == "payments"| summarize sum(value), by: {dt.cost.product}
fetch logs| filter dt.security_context == "confidential"| filter primary_tags.application == "payment-processing"
zremoteagentuserconfig.conf file rather than DT_TAGS. Host-level enrichment and central configuration are not supported.