Try it free

Scope Dynatrace configuration with DQL matchers

  • Latest Dynatrace
  • Explanation
  • 5-min read
  • Published Jul 23, 2026

The deployment-scope model described in Plan your tagging strategy provides a natural way to organize Dynatrace configuration along host groups, Kubernetes clusters, namespaces, and cloud accounts. As your environment grows, scope owners often need finer-grained control within their area of responsibility. Dynatrace provides data-driven configuration with DQL matchers that operates on the primary Grail fields and tags already present on your telemetry.

Data-driven configuration with DQL matchers

Fine-grained control is provided by DQL matchers that operate directly on data at query time or ingest time. This applies to:

  • Pipeline routing: Route telemetry to specific pipelines based on any combination of primary Grail fields and primary Grail tags.
  • Bucket selection: Direct data into specific Grail buckets based on field values.
  • Permissions: Define access control using permission-relevant primary Grail fields and dt.security_context.
  • Segments: Build filter definitions using any primary Grail field or primary Grail tag.

Because these capabilities operate on data, they support any level of granularity that your enrichment provides. If your telemetry carries a primary_tags.app tag, you can create a pipeline, bucket, permission, or segment that matches on that tag, regardless of whether the data comes from a host group, a Kubernetes namespace, or an API endpoint.

Move beyond entity-level scopes

In Dynatrace Classic, configuration was commonly defined at the host, process group instance, or service level. Entity-level scopes come with significant drawbacks:

  • Incompatible with configuration-as-code: Entity IDs don't exist before deployment. You can't reference a host or process group in a Git-managed configuration if the entity hasn't been discovered yet.
  • Dynatrace-specific concepts: Entity-level scopes don't align with how teams think about their environments. Teams think in applications, namespaces, clusters, and cost centers, not Dynatrace entity IDs.

Dynatrace now supports filter conditions on scoped configurations. These conditions are restricted to:

  • Primary Grail fields
  • Primary Grail tags
  • Curated host and process properties

These attributes are available at agent startup, at the edge, and in data-driven processing such as service detection.

A scope owner—for example, a Kubernetes cluster owner, or a host group owner—can configure behavior at scale while still targeting subsets of applications with a single configuration entry.

Why this approach scales

Using primary Grail fields and tags as the basis for all matchers offers several advantages over entity-level configuration:

  • No scalability bottlenecks: The agent evaluates matchers at startup and service detection matches statelessly. There is no centralized rule engine that becomes a bottleneck.
  • Lower maintenance: Adding a new application to a host group requires only setting the correct tags; the configuration automatically applies.
  • GitOps-friendly: All configuration references stable identifiers (field names, tag keys, tag values) rather than runtime entity IDs. You can use version control for your entire Dynatrace setup.

Kubernetes-specific considerations

For Kubernetes scopes, you can also use selected Kubernetes labels as filter conditions, provided the agent, edge components, and service detection all have access to them. This is useful for Kubernetes-native teams that already use labels to organize workloads.

The supported scopes for Kubernetes-aware configurations include:

  • Kubernetes cluster
  • Kubernetes namespace

Within these scopes, filter conditions can reference primary Grail fields, primary Grail tags, and Kubernetes labels to target specific workloads.

Related topics

  • Organize your data with primary Grail fields and tags
  • Primary Grail fields and tags
  • Best practices for enriching primary Grail fields and tags
  • Plan your tagging strategy
  • Configure security context
  • Configure cost allocation
Related tags
Dynatrace Platform