Upgrade from management zones to segments
- Latest Dynatrace
- Best practices
- 60-min read
This guide helps you to upgrade from management zones to segments in Latest Dynatrace, sharing best practices for fully supported scenarios.
Why upgrade?
With the introduction of Latest Dynatrace, it was necessary to introduce new concepts to meet the requirements for monitoring cloud and AI native environments in terms of scale and manageability.
While management zones have been used widely in Dynatrace to define access to data and filter data on a global level, in Latest Dynatrace they have been replaced by three new concepts, each tailored to satisfy the respective requirements of Enterprise environments:
- Data partitioning: Organize data logically and address performance and retention requirements.
- Data access: Stay flexible and meet compliance and security demands by defining fine-grained access to data and Dynatrace platform capabilities based on a user's context.
- Data segmentation: Provide real-time filtering on huge data sets without the need to define thousands of individual rules.
In this upgrade guide, you will find practical examples that show how to upgrade from existing management zones to segments.
What will you do?
Upgrading from management zones to segments follows three steps.
-
Identify your dimensions. Decompose your management zone names into their constituent attributes—for example,
app,stage,team. Each attribute becomes a separate segment dimension. -
Ensure enrichment. Segments rely on signals being enriched with the right attribute values at the data source. Without enrichment, segments cannot filter data correctly. See Enrichment for on-premises and virtual machine hosts, Enrichment for Kubernetes environments, and Enrichment for cloud environments for the available approaches.
-
Create your segments. With enrichment in place, configure segments in Settings > Environment segmentation > Segments.
Before you begin
New concepts
Management zones functioned as single, pre-baked groupings. A management zone like easytrade_prod encoded multiple dimensions into one name—for example, app=easytrade and stage=prod. Adding a new stage or application multiplied the number of zones, and filtering logic became hardcoded into zone names.
Segments work differently: they are built from individual dimensions (attributes and their values) that combine dynamically. The easytrade_prod zone becomes two independent dimensions—app and stage—that combine at query time. This is why there is no 1:1 mapping: a single management zone often encodes multiple dimensions that segments handle separately.
Breaking changes
Management zones also controlled access permissions. Segments do not replace this aspect of management zones. For the access control aspect, see Working with policies.
How to upgrade
Enrichment for on-premises and virtual machine hosts
For OneAgent installed on bare-metal servers, VMware hosts, or cloud instances without native hyperscaler tagging, the enrichment approach depends on whether a host serves one or multiple applications.
Without enrichment, segments cannot filter data from these hosts correctly. Choose the approach that matches your infrastructure before creating segments.
Dedicated infrastructure
Use this approach when a host serves a single application or team. The host group is automatically propagated across all associated signals, making it the primary enrichment signal.
In addition to the host group, define the following host-level metadata to cover security context, cost allocation, and segmentation:
- Security context:
dt.security_context=<value> - Cost center:
dt.cost.costcenter=<value> - Product:
dt.cost.product=<value> - Additional primary Grail tags (optional):
primary_tags.<key>=<value>
To add this metadata to hosts via Deployment Status
- Go to Deployment status and select OneAgents.
- Filter to the relevant hosts, for example by host group.
- Use the checkbox at the top of the table to select the hosts.
- In the command menu, select
modify host propertiesand then Run action. - Under Specify host properties to be added, add each key-value pair.
- Select Apply.
After the configuration, OneAgent restarts automatically.
- Logs: enriched after the OneAgent log module restarts. No application restart required.
- Spans: require a restart of the monitored application.
Shared infrastructure
Use this approach when multiple applications share a host. Host groups are not granular enough because all processes on the host share the same group. Instead, define enrichment attributes as environment variables for each process.
Set DT_TAGS and OTEL_RESOURCE_ATTRIBUTES on each process with the same metadata fields used for dedicated infrastructure:
dt.security_context=<value>dt.cost.costcenter=<value>dt.cost.product=<value>primary_tags.<key>=<value>
Note the semantic difference between DT_TAGS and OTEL_RESOURCE_ATTRIBUTES: they use different separators between key-value pairs. See the Cloud-native scenarios section on this page for a detailed example of the variable format.
After adding environment variables, restart the affected processes or containers.
Enrichment for Kubernetes environments
For Kubernetes environments monitored by Dynatrace Operator, there are three enrichment approaches with different levels of effort and granularity.
| Approach | Effort | Granularity | When to use |
|---|---|---|---|
primary Grail fields | Out of the box | Namespace-level | Simple setups; quick configuration for IAM, buckets, and segments |
Namespace annotations and labels | Minor Dynatrace configuration | Namespace-level | Environments with existing cloud-native tagging strategies; supports custom primary Grail tags |
Manual pod annotations | Requires code change | Pod-level | Pod-level granularity; supports custom primary Grail tags; does not enrich Kubernetes platform metrics or Kubernetes events |
For most production environments, use Namespace annotations and labels as the baseline. You can combine it with Manual pod annotations for workloads that need finer granularity—Manual pod annotations take priority where both are configured. Combining both requires Dynatrace Operator 1.6.2 or later.
Primary Grail fields
Dynatrace automatically populates k8s.namespace.name and k8s.cluster.name as primary Grail fields with no additional configuration. These are sufficient for IAM, bucket, and segment configuration in simple setups where namespace-level granularity is acceptable.
Namespace annotations and labels
If your environments already use Kubernetes labels and annotations to classify applications and teams, you can configure Dynatrace to map namespace-level labels into the standard enrichment fields.
To configure namespace enrichment
- Go to Settings > Cloud and virtualization > Kubernetes telemetry enrichment.
- Select Add rule.
- Set the Metadata type (Label or Annotation), the Source key, and the Target field (
dt.security_context,dt.cost.costcenter, ordt.cost.product). - To propagate the label value as a custom primary Grail tag without mapping to a standard field, enable Enrich telemetry with label/annotation directly.
New rules take up to 45 minutes to become effective. To apply changes immediately, restart Dynatrace Operator: kubectl -n dynatrace rollout restart deployment dynatrace-operator. After configuring enrichment, restart the application pods.
This enrichment applies at namespace level only. Labels and annotations set at workload level are not picked up by this setting.
Manual pod annotations
For pod-level granularity—for example, when workloads in the same namespace need different dt.security_context values—add Dynatrace metadata directly to your deployment manifests as pod annotations.
To add metadata annotations to a deployment
- Edit the deployment manifest and add the required annotations under
spec.template.metadata.annotations. - Apply the changes with
kubectl apply -f <manifest.yaml> -n <namespace>.
Manual pod annotations do not enrich Kubernetes platform metrics or Kubernetes events. For those signal types, configure enrichment at namespace level.
Enrichment for cloud environments
For cloud resources monitored via cloud connections (AWS, Azure, GCP), enrichment is largely automatic. Cloud attributes and customer-defined cloud tags are collected from the hyperscaler without additional configuration.
Cloud attributes such as aws.region, aws.account.id, azure.resource.group, and gcp.project.id are primary Grail fields that propagate to every signal out of the box.
To extend enrichment beyond the defaults, configure the following options in your cloud service settings:
- Tag enrichment: Specify a cloud tag key to propagate its value to all available signals (logs, metrics, spans, events).
- Dynatrace attribute enrichment: Map a cloud tag to a standard Dynatrace field (
dt.security_context,dt.cost.costcenter, ordt.cost.product) to drive access control and cost allocation from your existing cloud tagging.
For cloud compute resources where OneAgent is also installed (for example, AWS EC2), cloud tags do not automatically enrich process- and service-level signals. Use DT_TAGS as an environment variable on those processes to achieve process-level enrichment.
Auto-tagging scenarios
If you rely on entity auto-tagging to define your management zones, the following sections offer examples of how you can move from auto-tagging to segments.
Auto-tagging based on process name, host name, service name, or metadata
Other than in cloud native scenarios (Application-only OneAgent injection), when the tags are based on process name, host name, service name, or their metadata, we recommend tagging via host tags at the source.
The following example shows a possible tagging configuration.
To set the host tags for a management zone via the OneAgent deployment configuration page
-
Go to Deployment status and select OneAgents.
-
In the upper-right corner, select to list management zones, and then select a management zone for which you would add a new host tag.
-
Use the checkbox at the top of the table to select all hosts.
This displays a command menu in the lower-left corner of the page.
-
In the command menu, select
modify host tagsand then Run action.This starts the Remote configuration management wizard to carry out a configuration change on the selected OneAgents. It doesn't commit any changes until you select Apply changes and you confirm any required restarts. Before then, you'll be able to change or cancel the action.
-
Under Specify host tags to be added, select Add tag and specify the key-value pair tag to be added to as a host tag.
-
Select Next and review your changes.
If you now select Apply changes, OneAgent will be restarted on the selected hosts.
Repeat the above procedure for each management zone.
The result of this change is that, in Grail, on every signal sent by the selected hosts, the key-value will be on every signal as a field value combination.
Note that for signal data originating from processes with an injected code module, a process restart is required for the change to take effect.
Exceptions
Derived data such as service metrics, which are calculated based on span data, don't get every key-value that you add on the OneAgent side as a dimension. Currently, only keys will be carried over to derived data: dt.security_context, dt.cost.costcenter, and dt.cost.product.
However, you can propagate your OneAgent set tag to Davis problems. In settings, you need to configure your tag to be propagated to Davis problems.
- Go to
Settings > Dynatrace Intelligence > Root cause analysis > Problem fields. - Select New field.
If you need process-level granularity because multiple applications share a host, see Shared infrastructure.
In the segment configuration, you add a new variable with a DQL query.
- Go to Settings and select Environment segmentation > Segments to display the Segments page.
- On the Segments page, select Segment to create a segment.
- Describe the new segment:
-
Change
Untitled segmentto a useful segment name. -
Select Description to describe the segment.
-
Skip Visibility until you are ready to show the segment to everyone.
-
Under Variables, select Variable and then copy and paste the following query to the edit box. You need to replace
Servicewith the key you have added via the Deployment status page in the previous procedure.fetch dt.entity.host, from: -10d| expand tag = tags| fields tag| filter startsWith(tag, "[Environment]Service")| dedup tag| parse tag, "LD ':' LD:Service"| fields Service,tag
-
- Include other entities if needed; use this configuration as a template.
Auto-tagging based on host group names
Once the host group is set, all signals sent by the OneAgent are enriched with it as the dt.host_group.id field. There is no need to tag the data in Grail. In scenarios where a host group matches exactly a management zone, the variable definition could look as follows.
fetch dt.entity.host_group| fields hgName = entity.name, tag = concat("HG:", entity.name)
In the example above, the auto tag's name is HG. You need this in the variable definition because you want to match the Davis problems with that tag, since the Davis problems are enriched with the corresponding entity tags.
The segment definition looks as follows.
Note: The preview for segments based on entities currently is not working. This is a known issue that will be resolved soon.
Auto-tagging based on extraction of host group names
Suppose there is systematic host group naming, where the value of the host group name is composed of various environmental information split by a dash.
For example, you have <CMDBID>-<AppName>-<component>-<deploymentEnvironment>.
You're extracting here the CMDBIDs and tagging all related entities with the CMDBID. The CMDBID can consist of multiple apps and components. To keep the example DQL simple, let's limit this to three host groups per CMDBID.
In the DQL query for the variable definition, you would need to parse the environmental information. Let's call the information "dimensions".
To make the segment more user friendly, you can select the application name. The idea here is that, based on the application name, the host group name filter will be applied to all the data.
Here is the DQL query:
fetch dt.entity.host_group| parse entity.name, "LD:CMDBID '-' LD:app '-' ld:component '-' Ld:stage"| filter isNotNull(CMDBID)| fieldsAdd tag = concat("CMDBID:",CMDBID )| fields CMDBID, tag| dedup CMDBID| sort CMDBID asc
In the variable definition, you also have a field tag, which represents the CMDBID tag you put on every entity. You need that because you want to match the Davis problems with that tag, since the Davis problems are enriched with the corresponding entity tags.
The segment definition looks as follows.
Similarly, you can add additional segments for every dimension, and thus slice and dice all your observability data based on your dimensions derived from the host group name.
Auto-tagging based on Kubernetes namespace or cluster
All signals coming from a OneAgent that is deployed in a Kubernetes environment enrich every signal with the Kubernetes cluster name and the Kubernetes namespace.
Here the cluster or namespace name is propagated as tag to all the related entities. The segments variable definition would look as follows.
fetch dt.entity.cloud_application_namespace| fields namespace = entity.name| dedup namespace| fieldsAdd tag = concat("Namespace:", namespace)
In the variable definition, you also have a field tag, which represents the namespace tag you put on every entity. You need that because you want to match the Davis problems with that tag, since the Davis problems are enriched with the corresponding entity tags.
The segment definition looks as follows.
Auto-tagging based on host tags/host properties
If your auto tags are based on host tags set upon OneAgent installation or via the oneagentctl (as described in Define tags and metadata for hosts), defining the segment should be relatively easy. Every signal sent by the OneAgent is enriched with the tags defined on the OneAgent side.
Assume that the host tag you add has the tag key App. This means that, in the web UI, the tag is visible on the host level with the [Environment] prefix. Furthermore, you propagate the tag as tag App to all related entities.
The variable definition of the segment would look like this:
fetch dt.entity.host| expand tag = tags| fields tag| filter startsWith(tag,"[Environment]App")| parse tag, """'[Environment]App:' LD:app"""| fields app, tag = concat("App:", app)
In the variable definition, you also have a field tag, which represents the App tag you put on every entity. You need to do this because you need to add the entities to the segment.
The host tag you add on OneAgent doesn't enrich any derived signal on top of the raw data, like service metrics or Davis problems (except for field names/keys dt.security_context, dt.cost.costcenter, and dt.cost.product). However, for Davis problems, you can propagate your OneAgent set tag to Davis problems. In Settings, you need to configure your tag to be propagated to Davis problems as follows.
Non-auto tagging scenarios
Instead of relying on tags, your management zone definition could be based on process name, host name, service name, or metadata. If this is the case, follow the instructions in the Auto-tagging based on process name, host name, service name, or metadata section.
There, you need to introduce a new tag with a key such as Segment, and with the value set to the name of the management zone. This will allow you to segment all the data coming from OneAgents not running in cloud-native environments, where the OneAgent is injected into the application only.
Extension scenarios
Segments support filtering on signal data from extensions, not on entities created by extensions. With Dynatrace extensions, you can configure the enrichment attributes Security context, Product, and Cost center for every extension configuration.
In the following example, you see the enrichment configuration for a Postgres instance.
Assume that you have a management zone per product and that a host group is set up for every product. Your segment variable definition would be as follows.
fetch dt.entity.host_group| fields hg = entity.name
The segment definition would be as follows.
Note that you need to add the entities related to the host entity to the segment based on your needs.
Cloud-native scenarios
In cloud-native scenarios where the OneAgent is only injected into the application, you need to set environment variables so that the signals coming from that application are enriched with data.
Consider the following example.
This will make sure that every metric, Davis event, and span is enriched with the fields dt.security_context, App, and stage. In addition, the related process group instance metric gets that information added as tags.
Currently, you need to set those three environment variables. Note that the DT_TAGS and OTEL_RESOURCE_ATTRIBUTES variables might look the same, but there's a semantic difference (a colon instead of a space as a separator). Improvements for the future are already planned.
Derived data such as service metrics, which are calculated based on span data, don't get every key-value that you add within the environment variables. Currently, only keys will be carried over to derived data: dt.security_context, dt.cost.costcenter, and dt.cost.product.
However, you can propagate your OneAgent set tag to Davis problems. In Settings, you need to configure your tag to be propagated to Davis problems.
- Go to Settings > Dynatrace Intelligence > Root cause analysis > Problem fields.
- Select New field.
- Add values to Event field and Problem field for your tag key.