Enrich extensions with primary Grail fields and tags

• Latest Dynatrace
• How-to guide
• 8-min read
• Updated on Jul 24, 2026

Dynatrace enables you to enrich telemetry from extensions with primary Grail fields and tags, which you can use for segments, pipeline routing, bucket assignment, Grail permissions, and cost allocation, consistently across logs, metrics, spans, events, and Smartscape entities.

Enrichment can be configured per monitoring configuration of an extension, allowing you to define primary Grail fields and tags for your different deployments of the same extension.

The two extension types differ in how enrichment works:

For general guidance on primary Grail fields and tags, see Primary tags.

Prerequisites

Configure enrichment

Enrichment can be set at two levels within a monitoring configuration. Most support both levels, but some don't define individual endpoints—in those cases, only whole-configuration enrichment applies.

Select your preferred method.

PUT /api/v2/extensions/{extensionName}/monitoringConfigurations/{configurationId}

{
  "primaryTags": [
    {
      "key": "primary_tags.environment",
      "value": "production"
    },
    {
      "key": "primary_tags.team",
      "value": "platform"
    },
    {
      "key": "primary_tags.application",
      "value": "metrics-ingestion"
    }
  ]
}

PUT /api/v2/extensions/{extensionName}/monitoringConfigurations/{configurationId}

{
  "primaryFields": [
    {
      "key": "aws.region",
      "value": "us-east-1"
    }
  ],
  "primaryTags": [
    {
      "key": "primary_tags.environment",
      "value": "production"
    },
    {
      "key": "primary_tags.team",
      "value": "platform"
    }
  ]
}

Precedence

When the same key is set at multiple levels, the most specific definition wins. Endpoint-level enrichment takes priority over extension configuration enrichment, which in turn takes priority over host-level enrichment.

Remote extensions

Local extensions

For both extension types, endpoint-level tags and fields override the extension configuration values for matching keys. Keys not set at the endpoint level fall back to the extension configuration. For local extensions, keys not set in the monitoring configuration at all fall back to the OneAgent host.

OneAgent enrichment for local extensions

Local extensions automatically inherit both primary Grail fields and primary Grail tags from the OneAgent they run on. Any enrichment configured through the OneAgent enrichment guide—whether at install time, via oneagentctl, or through central configuration—is passed down to every local extension on that host as the base layer of enrichment.

You can also set primary tags explicitly at the host level using oneagentctl. This is useful when you want consistent tags across every local extension on a host without configuring each monitoring configuration individually.

oneagentctl --set-host-tag="primary_tags.environment=production"
oneagentctl --set-host-tag="primary_tags.team=platform"

For the full set of host-level and process-level options, see the OneAgent enrichment guide.

Query enriched data in Grail

Primary Grail fields and tags applied through extension configuration appear as top-level fields and can be queried with DQL:

fetch metrics
| filter primary_tags.team == "platform" AND primary_tags.environment == "production"

fetch metrics
| filter dt.cost.costcenter == "12345"
| summarize sum(value), by: {dt.cost.product}

fetch logs
| filter dt.security_context == "confidential"
| filter primary_tags.application == "metrics-ingestion"

Limitations