Primary Grail fields and tags enrichment through OneAgent

• Latest Dynatrace
• Explanation
• 10-min read
• Updated on Mar 11, 2026

OneAgent version 1.331+

OneAgent can enrich telemetry data at the source with custom metadata before sending metrics, spans, logs, events, and entities. The resulting data is immediately usable for platform features like segments, pipeline routing, bucket assignment, and cost allocation.

Why OneAgent-based enrichment?

Enriching primary Grail fields and tags at the OneAgent level empowers teams to take ownership of enrichment at deployment time. By enriching at the source, data is consistently enriched across all signals and Smartscape nodes from the very beginning.

Host-level enrichment of primary Grail fields and tags automatically propagates to Smartscape nodes, including hosts, processes, containers, networks, disks, and their associated signals. This approach eliminates the need for additional configuration in Dynatrace and allows enrichment responsibility to be delegated to the teams managing deployments. In Latest Dynatrace, primary tags and primary fields are the foundation for OpenPipeline routing, bucket assignment, Grail permissions, cost allocation, data segmentation, and alerting.

primary_tags.environment=production
primary_tags.team=bravo
primary_tags.application=payment-processing
dt.security_context=pci-compliant
dt.cost.costcenter=payments

Data enrichment with primary Grail fields and tags

Primary Grail fields

Primary Grail fields defined in the semantic dictionary are automatically enriched by OneAgent. Most primary Grail fields are determined by OneAgent and can't be modified.

You can define the following primary Grail fields at the OneAgent level for security and cost allocation:

Primary Grail tags

Primary Grail tags are customer-defined attributes that are automatically added to all ingested telemetry. They are identified by the reserved primary_tags. prefix and enable you to organize your data based on your most important organizational attributes. Examples include:

Set up primary Grail fields and tags for hosts and processes

You can configure primary Grail tags and fields in the following ways:

Option 1: Define fields and tags at OneAgent deployment

You can set primary Grail fields and tags at installation time by passing --set-host-tag parameters directly to the OneAgent installer. OneAgent will enrich all telemetry data from that host with the provided primary tags and fields.

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"

For more information on customizing OneAgent installations, see Customize OneAgent installation on Linux or Customize OneAgent installation on Windows.

Option 2: Define fields and tags for existing OneAgent installations using oneagentctl

Use oneagentctl to manage primary Grail fields and tags programmatically. OneAgent will enrich all telemetry data from that host with the provided primary tags and fields. For command details, see OneAgent configuration via command-line interface.

# Set fields for cost allocation and security
oneagentctl --set-host-tag="dt.cost.costcenter=12345"
oneagentctl --set-host-tag="dt.cost.product=checkout-service"
oneagentctl --set-host-tag="dt.security_context=confidential"

# Set primary tags
oneagentctl --set-host-tag="primary_tags.environment=production"
oneagentctl --set-host-tag="primary_tags.team=bravo"
oneagentctl --set-host-tag="primary_tags.business_unit=finance"

Option 3: Define fields and tags at process level using DT_TAGS

When you use the DT_TAGS environment variable at the process level, the OneAgent enriches data for this process. Any defined primary tag or field in this environment variable is enriched on all telemetry data for that process and overrides their equivalents on the host level.

The process-level environment variable takes precedence for process-scoped signals: when you define the same primary tag or field using DT_TAGS and at the host-level, the one that is closer to the monitored entity is taken and overrides the host-level value for the same key.

DT_TAGS="primary_tags.environment=production primary_tags.team=bravo primary_tags.application=payment-processing" java -jar checkout-service.jar

Precedence, overrides, and limits

When the same tag key or field is set at both the host and process levels, the process-level definition (DT_TAGS) takes precedence and overrides the host-level one for that process. Host-level tags and fields apply to all observability data from a host unless a process explicitly sets the same key using DT_TAGS.

Example

Tag limits

You can define up to 20 tags for host- or process-level enrichment. When more than 20 tags are defined, the first 20 take precedence. Tags defined at the process level override the host-level tags.

Query enriched data in Grail

Primary Grail fields and tags appear as top-level fields in the data and can be queried with DQL as follows.

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"

Limitations

The following are not covered by OneAgent primary grail fields and tags: