Upgrade classic OpenTelemetry tagging to primary Grail tags
Latest Dynatrace
Upgrade guide
6-min read
Published Sep 01, 2026
This guide helps you upgrade from classic OpenTelemetry resource-attribute tagging to primary Grail tags. Once upgraded, the ownership, environment, and cost context you already set on your telemetry works consistently for routing, permissions, and Cost Allocation across every signal, without extra entity-tagging rules to maintain.
Why upgrade?
No entity detour: Resource attributes that follow the primary_tags.* convention are recognized as primary Grail tags directly on spans, metrics, and logs, without needing an entity to carry the context first.
Reuse your existing resource attributes: If you already set organizational context through OTEL_RESOURCE_ATTRIBUTES or a Collector processor, renaming the relevant keys to the primary_tags.* convention is often enough.
Ready for permissions and Cost Allocation: The same convention also covers dt.security_context, dt.cost.costcenter, and dt.cost.product.
Built-in infrastructure context: If your OpenTelemetry telemetry reaches Dynatrace through OneAgent injection or the Dynatrace Operator, primary Grail fields such as dt.host_group.id, k8s.cluster.name, and k8s.namespace.name are enriched automatically.
What will you do?
First, list the resource attributes your Dynatrace Classic setup relies on for tagging. Then, map each one to a primary Grail field, a primary Grail tag, or a special field. Finally, enrich them at the source, verify the result with DQL, and retire the classic rules.
Before you begin
Prerequisites
Ability to set or change OTEL_RESOURCE_ATTRIBUTES at deploy time, or to edit your OpenTelemetry Collector configuration.
A list of the resource attributes your current Classic auto-tagging rules and management zones depend on.
Prior knowledge
Familiarity with OpenTelemetry resource attributes and, if used, Collector processor configuration.
Auto-tagging rules and management zones built from resource-attribute-derived entity tags are not evaluated for Grail data and are not used in any app. They remain supported only in Classic pages.
A central primary Grail tag configuration for standalone OpenTelemetry resource attributes isn't available yet. If your data originates from Kubernetes workloads, Kubernetes-side central configuration is already available. See Enrich Kubernetes telemetry with primary Grail fields and tags.
Only resource attributes that follow the exact primary_tags.<key>=<value> convention are recognized as primary Grail tags. See Limitations for details.
How to upgrade
1. List your Classic OpenTelemetry tagging setup
Before changing anything, list what your Classic setup currently depends on.
List the resource attributes your services currently set, and the auto-tagging rules or management zones built from the resulting entity tags.
Note which attributes are infrastructure identifiers likely already covered by a built-in primary Grail field (for example, k8s.namespace.name, dt.host_group.id), versus organizational context that needs an explicit primary Grail tag.
List the dashboards, alerts, or permission policies that depend on the management zones built from these tags.
You have a list of resource attribute keys to upgrade, split into those already covered by a primary Grail field and those that need to become a primary Grail tag.
2. Map Classic resource attributes to primary Grail fields and tags
For each remaining attribute, decide what it becomes in the new model.
If the attribute only reflects infrastructure context already covered by a primary Grail field, mark it as redundant instead of upgrading it.
If the attribute encodes organizational context (team, application, cost center, business unit), decide on a primary_tags.<key> name for it.
If the attribute 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 resource attribute to a primary Grail field, primary Grail tag, or special field.
3. Enrich at the source
Apply the mapping using the option that touches the fewest places, starting with the least invasive.
If a value already varies only by cluster, namespace, or host group, check whether a built-in primary Grail field already covers it. If so, no configuration is needed.
If a Collector sits in front of your services, add or rename attributes centrally there using a processor, rather than changing each service. See Enrich at source with resource attributes.
Where you control deployment directly, set or update OTEL_RESOURCE_ATTRIBUTES at deploy time:
For attributes that should drive permissions or Cost Allocation instead of a generic primary tag, set dt.security_context, dt.cost.costcenter, or dt.cost.product the same way.
If you can't change the attribute at the source, for example in a third-party library you don't control, configure an OpenPipeline primary Grail tag rule to derive it instead.
Redeploy or restart the affected service or Collector, then continue to the next step to verify the result.
4. Verify enrichment in Grail
Confirm the new tags and fields are present on the signals they should cover.
Run a DQL query against a relevant signal type for a service you know carries the updated resource attribute, for example:
fetch spans
| filter primary_tags.team == "alpha" AND primary_tags.app == "myapp"
For security context or Cost Allocation attributes, confirm the value with a targeted filter or summary:
fetch logs
| filter dt.security_context == "confidential"
Spot-check a service that previously relied on the Classic entity tag and confirm the equivalent primary Grail tag is now present on its telemetry.
The query returns the expected records with the new tag or field populated, matching what the old entity tag used to produce.
5. Retire redundant Classic 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 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 Classic pages. They're unaffected by this upgrade 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 Classic pages still require.
FAQ
Do I need to change every service instrumentation individually?
Not necessarily. If a Collector sits between your services and Dynatrace, you can add or rename attributes centrally in the Collector instead of touching every service.
What takes precedence if the same key is set in multiple places?
The most recently written value wins as telemetry moves through the pipeline: an OpenPipeline-derived value takes precedence over a Collector-level resource attribute, which takes precedence over an SDK-level resource attribute. See Precedence for details.
What if I need a primary Grail tag derived from more than one resource attribute?
Use OpenPipeline processing to derive the combined value and write it as a primary_tags.* field, rather than trying to express the combination as a single resource attribute at the source.