Metadata enrichment is the foundation of the Latest Dynatrace platform. In Dynatrace Classic, observability signals were tightly coupled to entities through management zones. In the latest platform, each data point is treated independently and must carry its own metadata. A solid enrichment strategy means that every downstream configuration—IAM, segmentation, and cost allocation—works correctly the first time.
Primary Grail Fields are commonly used filter criteria for infrastructure-related data. When applicable, they are present on all signal types—spans, logs, metrics, Smartscape topology, and events—automatically.
The most important Primary Grail Fields for infrastructure monitoring are:
Use Primary Grail Fields as the first-choice filter for segments, IAM boundaries, and bucket routing. Because they propagate to every signal type automatically, they give you consistent cross-signal filtering without additional configuration.
Not all metadata is a Primary Grail Field. Fields like java.jar.file are local to specific signal types. If you filter a segment by a non-primary field, the filter applies only to signals that carry that field, not to all signal types. Design your enrichment strategy around Primary Grail Fields where possible.
When Primary Grail Fields are not granular enough for your use case—for example, when multiple applications share the same host group—use Primary Grail Tags. These are identified by the prefix primary_tags.*.
Common Primary Grail Tags to configure:
primary_tags.team: identifies the owning teamprimary_tags.app: identifies the applicationprimary_tags.stage: identifies the environment (production, staging, development)Configure these tags alongside Dynatrace-specific attributes such as dt.security_context, dt.cost.costcenter, and dt.cost.product to support IAM access control and cost allocation.
Plan your Primary Grail Tag schema before installing OneAgent or Dynatrace Operator. Tags set at install time are applied to all signals from the start of monitoring, avoiding the need to reconfigure hosts or processes later.
Configure enrichment fields and tags when you install or configure observability components. Setting enrichment at the source—during OneAgent installation, Kubernetes Operator deployment, or OpenTelemetry Collector setup—ensures all signals carry the required metadata from the first data point.
For a OneAgent installation, you can set host group, security context, cost allocation fields, and Primary Grail Tags as part of the install command. For example:
--set-host-group=onPrem_easytravel_staging--set-host-tag=dt.security_context=easytravel--set-host-tag=dt.cost.costcenter=easytravel--set-host-tag=dt.cost.product=easytravel--set-host-tag=primary_tags.team=alpha--set-host-tag=primary_tags.app=easytravel--set-host-tag=primary_tags.stage=staging
Enrichment applies only to signals ingested after the configuration is active. Historical data ingested before enrichment was configured will not carry the added metadata.
OneAgent version 1.337 or later is required for primary_tags.* and dt.security_context enrichment. Version 1.343 or later is required for central enrichment rule configuration. Check component versions before configuring enrichment rules.
After configuring enrichment, validate that metadata is consistently applied across all signal types before proceeding to IAM configuration, segment creation, or bucket routing.
To validate enrichment
A signal type that does not appear in a segment filtered by a Primary Grail Field indicates an enrichment gap. Resolve enrichment gaps before starting IAM or segment configuration; gaps propagate into misconfigured access control and broken segmentation.
Use the Enrichment Coverage notebook to measure enrichment percentage across all signals and identify which hosts, processes, or services are missing required metadata fields. Run the notebook regularly during the enrichment stage to track progress.
Explore the other best practices for this stage, or return to Enrich your observability signals to continue your upgrade.