Upgrade OneAgent classic auto-tagging to primary Grail tags
Latest Dynatrace
Upgrade guide
7-min read
Published Sep 08, 2026
OneAgent setups in Dynatrace Classic typically rely on auto-tagging rules and management zones to attach ownership, environment, and cost context to hosts, processes, and services: an entity-first model, where you tag the entity, then look at the entity's data. Latest Dynatrace flips this: it's data-first. Primary Grail fields and tags are enriched directly on every signal OneAgent sends, so the same context is available on logs, metrics, spans, events, Davis events, and problems without any propagation rules.
Upgrading replaces the classic auto-tagging rules and management zones with a leaner setup:
One central configuration surface: Ingest enrichment configuration lets you promote existing host and process context to primary Grail tags for an entire environment or host group, without touching individual hosts.
Consistent access, routing, and cost allocation: The same primary Grail fields and tags (plus dt.security_context, dt.cost.costcenter, and dt.cost.product) drive OpenPipeline routing, bucket assignment, Grail permissions, and cost allocation, with no separate configuration per capability.
List your classic OneAgent auto-tagging rules and map each one to a primary Grail field, a primary Grail tag, or a special field (dt.security_context, dt.cost.costcenter, dt.cost.product). Then enrich at the source or centrally, verify the result with DQL, and retire the redundant classic rules.
Auto-tagging rules and management zones are not evaluated for Grail data and are not used in any app. They remain supported only in a Dynatrace Classic page.
Only dt.security_context, dt.cost.product, and dt.cost.costcenter are accepted as special target fields outside the primary_tags.* convention. Any other custom target is rejected.
Up to 20 primary tags are enriched per host or process. Additional tags are silently dropped.
Cloud tags are not yet available as input fields for OneAgent.
How to upgrade
1. List your classic tagging setup
Before changing anything, list what your classic setup currently does so you can map it one-to-one to the new model.
Export or list your OneAgent-related auto-tagging rules, noting the condition (for example, host group name, process name pattern) and the resulting tag key/value.
List the management zones built from those tags, and the permissions, dashboards, or alerting rules that depend on them.
Flag which rules only exist to surface infrastructure context that's now a built-in primary Grail field (host group, Kubernetes namespace/cluster, AWS account, Azure subscription). These rules can typically be retired outright rather than migrated.
You have a complete list of rules to migrate and a shortlist of rules that are now redundant.
2. Map classic tags to primary Grail fields and tags
For each remaining rule, decide what it becomes in the new model.
If the rule only reflects infrastructure context already covered by a primary Grail field, mark it as redundant instead of migrating it.
If the rule encodes organizational context (team, application, cost center, business unit), decide on a primary_tags.<key> name for it.
If the rule feeds permissions or cost allocation, map it to dt.security_context, dt.cost.costcenter, or dt.cost.product instead of a generic primary tag.
You have a mapping table that maps each classic rule to a primary Grail field, primary Grail tag, or special field.
3. Enrich at the source
Apply the mapping using the enrichment method that fits each case, starting with the least invasive option.
If a value already varies only by host group, cluster, namespace, or cloud account, check whether a built-in primary Grail field already covers it. If so, no configuration is needed.
For values you control at install time or that differ by process, set them with the installer, oneagentctl, or DT_TAGS. See Enrichment guide for the exact syntax for each case.
For values already present as a host tag, host group, or naming convention, create a rule in Ingest enrichment configuration instead of touching hosts individually.
If none of the above covers a case, evaluate whether you need an OpenPipeline primary Grail tag rule (which applies globally across all signal types and configuration scopes) or a more targeted OpenPipeline processing rule scoped to a specific signal type. The right choice depends on how broadly you want the enrichment to apply.
When creating ingest enrichment configuration rules, scope them to a host group whenever possible to keep enrichment targeted and preserve the option to override with more specific rules at a narrower scope.
Rerun the DQL query from the next step to confirm the tag applies to the hosts and processes you expect.
4. Verify enrichment in Grail
Confirm the new tags and fields are present on the signals they should cover.
Run a DQL query against the signal type most relevant to the migrated rule, for example:
fetch spans
| filter primary_tags.team == "bravo" AND primary_tags.environment == "production"
For security context or cost allocation fields, confirm the value with a targeted filter or summary:
Spot-check a host or process that previously relied on the classic rule and confirm the equivalent primary Grail tag or field is now present on its telemetry.
The query returns the expected records with the new tag or field populated, matching what the old auto-tagging rule produced.
5. Retire redundant classic auto-tagging rules
Once permissions, routing, and cost allocation are cut over to the primary Grail model, clean up what's no longer needed.
Re-point any dashboards, alerts, or permission policies that still reference the old management zones or auto-tagging rules to the equivalent primary Grail fields, tags, or segments.
Delete the auto-tagging rules and management zones flagged as redundant when you listed your classic setup.
Keep any auto-tagging rules still required for Dynatrace Classic pages. They're unaffected by this migration and can stay in place as long as those pages are in use.
Dashboards, alerts, and permissions continue to work using primary Grail fields and tags, and you retain only the classic auto-tagging rules and management zones that Dynatrace Classic pages still require.
FAQ
Can I run classic auto-tagging and primary Grail tags at the same time?
Yes. They don't conflict. Auto-tagging rules continue to affect entities in Dynatrace Classic pages, while primary Grail tags and fields are enriched independently across all signals. Migrate at your own pace.
Do I need to reinstall OneAgent to get primary Grail tag support?
No, as long as your OneAgent version is 1.333 or later (or 1.343+ for Ingest enrichment configuration). You can add host-level or process-level tags to an existing installation with oneagentctl or by redeploying with new environment variables. No reinstall is required.
What takes precedence if the same tag key is set in multiple places?
Process-level (DT_TAGS) wins over host-level (installer or oneagentctl), which wins over an Ingest enrichment configuration rule. Host-level tags still fill in any keys the process didn't override.