Try it free

Enrich OneAgent telemetry with primary Grail fields and tags

  • Latest Dynatrace
  • How-to guide
  • 10-min read

This documentation describes the new tagging model for Latest Dynatrace. Some capabilities are still rolling out. If you're currently using Dynatrace Classic auto-tagging, see Dynatrace Classic versus Latest Dynatrace to understand how your existing setup maps to the new model.

OneAgent enriches telemetry at the source with primary Grail fields and tags before sending logs, metrics, spans, events, and entities to Dynatrace. This gives you consistent metadata across all signal types for segments, pipeline routing, bucket assignment, and cost allocation. Host-level enrichment automatically propagates to all Smartscape nodes (hosts, processes, containers, networks, disks) and their signals.

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

Platform capabilityHow enrichment helps

Data routing

Route data to specific pipelines based on primary_tags.*, dt.security_context, dt.cost.costcenter, or dt.cost.product

Bucket assignment

Assign target retention bucket based on primary_tags.*, dt.security_context, dt.cost.costcenter, or dt.cost.product

Grail permissions

Derive security context for data access control

Cost allocation

Track costs per team or product with dt.cost.costcenter and dt.cost.product

Segments

Define segments based on tags and fields to filter data across Dynatrace apps

Alerting

Create targeted alerts and notifications based on tags and fields

Enrichment guide

Follow this hierarchy. Start with step 1 and continue only if the previous step doesn't meet your needs.

1. Built-in primary Grail fields

OneAgent automatically detects and enriches primary Grail fields such as dt.host_group.id without any manual configuration. When OneAgent runs on Kubernetes (typically rolled out via the Dynatrace Operator), k8s.cluster.name and k8s.namespace.name are also populated automatically. If these built-in fields cover your filtering and access control needs, no additional setup is required.

2. Recommended: Enrich at source

Define tags and fields directly on the host or process so data is enriched before it leaves the host. You can apply tags at two scopes:

  • Host-level: Tags apply to all signals from the host and its Smartscape nodes. Set them at install time with --set-host-tag, or at any later point on an existing installation with oneagentctl --set-host-tag.
  • Process-level: Tags apply only to a specific process via the DT_TAGS environment variable. Use this when different processes on the same host need different metadata, or when using serverless and managed container platforms where you can't configure the host itself, for example, AWS Lambda and Azure Functions. When the same key is set at both scopes, the process-level value wins for that process.

Linux installer

Dynatrace-OneAgent-Linux.sh --set-host-tag="primary_tags.environment=production" --set-host-tag="dt.security_context=confidential"

Windows installer

.\Dynatrace-OneAgent-Windows.exe --set-host-tag="primary_tags.environment=production" --set-host-tag="dt.security_context=confidential"

oneagentctl

# Primary Grail fields
oneagentctl --set-host-tag="dt.cost.costcenter=12345"
oneagentctl --set-host-tag="dt.security_context=confidential"


# Primary Grail tags
oneagentctl --set-host-tag="primary_tags.environment=production"
oneagentctl --set-host-tag="primary_tags.team=bravo"
DT_TAGS="primary_tags.environment=production primary_tags.team=bravo primary_tags.application=payment-processing" java -jar checkout-service.jar

On serverless platforms, OneAgent can't auto-detect certain primary fields. Provide them via DT_TAGS at deploy time:

  • AWS: aws.account.id, aws.region
  • Azure: azure.subscription, azure.resource.group, azure.location

3. Ingest enrichment configuration

Use Ingest enrichment configuration to apply primary tags and enrichments, including Security context, Cost center, and Cost product, to all telemetry coming from hosts and processes. With this approach:

  • No changes on the hosts are required.
  • No agent restart is needed.

Rules take effect on the next agent enrichment refresh cycle.

Enriching all data from a host based on a process or service property is not supported.

If your hosts already carry the context you want, through existing host tags, host groups, or a naming convention, you can promote it with Ingest enrichment configuration.

Create an enrichment rule

Ingest enrichment configuration requires OneAgent version 1.343+.

  1. Go to Settings Settings > Collect and capture > Ingest enrichment configuration and select New rule. To automate rule creation instead, see the Ingest enrichment configuration schema for use with the Settings API.

  2. Define the condition that selects the hosts and processes to enrich, using the input fields OneAgent provides (for example dt.host_group.id, host.name, host.tags.<key>, k8s.cluster.name, k8s.namespace.name, aws.account.id). Conditions support matchesValue (equals), matchesPhrase (contains, begins/ends with), isNull, isNotNull, and the AND, OR, NOT operators.

    • matchesValue(dt.process_group.detected_name, "example-process-name")
    • matchesPhrase(host.name, "prod-host-")

    See the DQL string functions documentation for details on matchesValue and matchesPhrase.

  3. Define the enrichments to apply. Enter either a static value or a DPL transformation on an input field.

    • To enrich with Security context, Cost center, or Cost product, select the corresponding field.
    • For a primary tag, enter the tag key.

  4. Review the Resulting mapping preview. It shows how the input fields are mapped onto all telemetry from the matching hosts and processes.

  5. Select Create.

Enrichments defined on a host are inherited by the processes, containers, disks, and network interfaces on that host. Enrichment keys are stored under primary_tags.<key>, except for dt.cost.costcenter, dt.cost.product, and dt.security_context, which are applied as-is.

You can also add a Custom rule that enriches a static string literal on all telemetry from the matching hosts and processes. The static literal can be used as Security context, Cost center, Cost product, or directly as a primary tag.

Derive tags from host names with a transformation

If meaningful metadata is encoded in the host name or process group name, use a DPL transformation on the input field to derive one or more primary tags. A single transformation can populate multiple tags. If the pattern doesn't match, no tag is applied. There is no partial output.

Supported DPL syntax

The Dynatrace Pattern Language (DPL) support in OneAgent covers the core structural building blocks of the language.

ConstructSupported

Matchers

LD/LDATA captures any sequence of characters within a single line. The positional anchors BOS/BOF (beginning of string) and EOS/EOF (end of string) anchor patterns to string boundaries.

Literal expressions

Single-quoted ('text') and double-quoted ("text") string literals, for matching fixed text.

Character groups

[abc], [a-z], [^abc], including character ranges and negation via ^ or !. The escape sequences \t, \r, \n, and \\ are recognized within groups.

Grouping

Sequence groups ((A B C)) and alternative groups ((A | B | C)), including nested groups.

Modifiers

Quantifiers (*, +, {min,max}, {min,}, {,max}, {val}), the optional modifier (?), and export names (:value) for capturing matched content into named fields.

Example: extract environment, team, region, role, and index from host name

For a naming convention <env>-<team>-<region>-<role>-<index> (for example prod-payments-eu-web-01), create 5 separate rules:

  • Each rule uses host.name as the source attribute and targets a primary tag.
  • All 5 rules share the same condition: matchesPhrase(host.name, "*-*-*-*-*").
RulePrimary tag keyResulting mappingValue extraction expression

1

environment

host.name primary_tags.environment

LD:value'-'LD'-'LD'-'LD'-'LD

2

team

host.name primary_tags.team

LD'-'LD:value'-'LD'-'LD'-'LD

3

region

host.name primary_tags.region

LD'-'LD'-'LD:value'-'LD'-'LD

4

role

host.name primary_tags.role

LD'-'LD'-'LD'-'LD:value'-'LD

5

index

host.name primary_tags.index

LD'-'LD'-'LD'-'LD'-'LD:value

If host.name doesn't match the expected five-segment pattern, the DPL extraction fails, and no tag is applied for that rule. There is no partial output.

Scopes

Ingest enrichment configuration is supported at the environment scope and host group scope. Set a broad rule at environment scope and fine-tune it with a more specific rule at host group scope. When the same key is set at multiple scopes, the more specific definition wins, in which case the host group scope takes precedence over the environment scope.

Rule order matters: reorder rules by dragging them in the configuration page to change which one takes precedence.

When the same key is defined multiple times within a single source, the first matching rule wins.

Limitations

  • After a change in Ingest enrichment configuration, there may be a short delay before agents retrieve the update (typically one refresh cycle, around five minutes).
  • Cloud tags are not yet available as input fields for OneAgent. See AWS, Azure, or GCP documentation for the cloud-tag options.
  • Regex and nested condition functions (for example isNull(isNotNull(x))) are not supported.

4. Use OpenPipeline for ingest-time enrichment

If none of these approaches work, use OpenPipeline primary Grail tag rules to derive or assign primary tags at ingest-processing time. Use this as a fallback for environments with constraints that prevent enrichment at an earlier stage.

Precedence

When the same key is set at multiple scopes, the more specific definition wins:

  1. Process-level: (DT_TAGS)
  2. Host-level: (installer or oneagentctl)
  3. Ingest enrichment configuration rule.

Host-level tags fill in any keys that the process didn't override.

Working example
ResourceEnrichment levelDefined valuesEnrichment result

Host

oneagentctl or installer

primary_tags.business_unit=ecommerce, primary_tags.environment=dev

primary_tags.business_unit=ecommerce, primary_tags.environment=dev

.NET Process

DT_TAGS (process level)

primary_tags.business_unit=finance, primary_tags.team=alpha

primary_tags.business_unit=finance, primary_tags.team=alpha, primary_tags.environment=dev

Java Process

DT_TAGS (process level)

primary_tags.business_unit=payment, primary_tags.team=hearts, primary_tags.environment=hardening

primary_tags.business_unit=payment, primary_tags.team=hearts, primary_tags.environment=hardening

Any other process

—

—

primary_tags.business_unit=ecommerce, primary_tags.environment=dev

Coverage by environment

The following table shows which enrichment methods are available in each environment.

EnvironmentHost-level (installer, oneagentctl)Process-level (DT_TAGS)Ingest enrichment configuration

Linux or Windows hosts

OneAgent extensions

Kubernetes workloads 1

AWS Lambda 2

—

—

Azure Functions 2

—

—

Mainframe 3

—

—

1

Enrichment on Kubernetes requires OneAgent to be deployed via the Dynatrace Operator. Namespace labels and annotations can also be promoted through Kubernetes-side central configuration and reach OneAgent-emitted signals. For details, see Domain: Kubernetes.

2

Serverless workloads run only the OneAgent code module, so the installer, oneagentctl, and ingest enrichment configuration are not available. Ingest enrichment configuration would also introduce startup latency that's incompatible with these low-latency, volatile workloads. Enrich tags and fields through DT_TAGS when deploying the workload.

3

On mainframe, process-level enrichment is configured in the zremoteagentuserconfig.conf file, not via DT_TAGS.

Query enriched data in Grail

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

Filter spans by team and environment
fetch spans
| filter primary_tags.team == "bravo" AND primary_tags.environment == "production"
Cost allocation aggregation
fetch bizevents
| filter dt.cost.costcenter == "payments"
| summarize sum(value), by: {dt.cost.product}
Security context filtering
fetch logs
| filter dt.security_context == "confidential"
| filter primary_tags.application == "payment-processing"

Limitations

  • Primary Grail field and tag enrichment requires OneAgent version 1.333+.
  • Dynatrace Classic is not supported.
  • On mainframe, only process-level enrichment is available, configured in the zremoteagentuserconfig.conf file rather than DT_TAGS. Host-level enrichment and ingest enrichment configuration are not supported.
  • Enriching all data from a host based on a process or service property is not supported.
  • Up to 20 primary tags per host or process; excess tags are silently dropped without a warning.

Related topics

  • OneAgent configuration via command-line interface
  • Set up Grail permissions for OneAgent
  • Global field reference
  • Set up Cost Allocation for OneAgent deployments
  • Primary Grail fields and tags
  • Organize your data with primary Grail fields and tags
  • Plan your tagging strategy
  • Best practices for enriching primary Grail fields and tags
  • Differences between classic auto-tagging and primary Grail tags
Related tags
Application Observability