Upgrading from Dynatrace Classic to the latest platform is a complex, team-coordinated process that spans multiple capability areas. The best practices in this guide are drawn from upgrade engagements across enterprise accounts and validated by Dynatrace's Center of Excellence (CoE) and Customer Success teams.
This guide presents a recommended sequence, not a mandatory one. Not every stage applies to every account: some stages depend on capabilities or integrations tied to specific licensing tiers, and some may be out of scope depending on your existing configuration. Use this as a reference to plan your upgrade, skip stages that don't apply, and revisit deferred stages as your licensing or requirements change.
Dynatrace Classic is built on static, precomputed configurations: management zones, metric selectors, and notification channels that require manual upkeep as your environment scales. Latest Dynatrace replaces this model with a dynamic, query-based platform backed by Grail.
The upgrade moves through 11 stages. The first two establish the foundation before any capability migration begins; the remaining stages progressively migrate capabilities and configurations until your environment is fully running on Latest Dynatrace.
| Stage | Description |
|---|---|
| 1. Upgrade scoping | Inventory your Dynatrace Classic configuration, agree on what gets migrated, retired, or deferred, and get stakeholder sign-off before any technical work begins. |
| 2. Enrich ingested signals | Apply the metadata that access boundaries, segments, and cost allocation all depend on. Validate coverage before proceeding; insufficient enrichment affects all downstream stages. |
| 3. Upgrade management zones to IAM and segments | Replace classic management zones with IAM boundaries and dynamic segments scoped to dt.security_context. |
| 4. Upgrade observability data and settings | Migrate RUM, cloud integrations, extensions, and log ingestion to the latest platform. |
| 5. Partition data | Assess signal volumes and configure bucket routing to optimize query performance and enforce retention policies per your compliance requirements. |
| 6. Upgrade configurations and settings | Migrate service naming, metrics, SLOs, and processing rules. Complete before starting stages 7 and 8. |
| 7. Upgrade dashboards | Migrate actively used classic dashboards using the built-in converter, then rebuild unconverted tiles and management zone filters manually. Runs in parallel with stage 8. |
| 8. Upgrade metrics alerting and maintenance windows | Convert classic metric alerts, recreate entity-selector-based alerts with DQL, and upgrade maintenance windows. Runs in parallel with stage 7. |
| 9. Upgrade team-based and global alerting | Migrate problem notifications, security notifications, and enterprise ITSM integrations to event-driven Workflows. Requires stages 7 and 8 to be complete. |
| 10. Upgrade remaining entities and metrics | Update DQL queries in dashboards, alerts, and workflows to reference Smartscape 2.0 entity types. |
| 11. Upgrade API and tokens | Audit classic API usage, create OAuth clients with granular scopes, and migrate integrations to Latest Dynatrace endpoints. |
The following roles contribute to the upgrade journey across different stages. Refer to each stage guide for the specific stakeholders required at that step.
| Stakeholder | Role across the upgrade |
|---|---|
| Dynatrace Admin | Primary point of contact for all technical configuration, environment access, and deployment coordination. |
| Application Team Leads | Validate that access boundaries, dashboards, alerts, and SLOs meet their team's operational needs. |
| Project Sponsor | Approves scope, confirms out-of-scope decisions, and signs off on success criteria. |
| Data Owner | Owns the source-of-truth for dimension mappings used in enrichment. |
| IdP Owner | Configures SSO, SAML/OIDC integration, and manages group synchronization. |
| DevOps / Platform Eng. | Owns CI/CD pipelines, automation scripts, cloud integrations, and extensions. |
| Cloud Ops | Needed for cloud connection upgrades and resource discovery validation. |
| SRE / Observability Eng. | Owns SLO definitions, calculated metric conversions, and DQL query migrations. |
| Dashboard Owners | Confirm converted tiles, filters, and variables match their original intent. |
| IT Operations | Own enterprise ITSM integrations (ServiceNow, PagerDuty) and validate bidirectional workflow behavior. |
| Security / Compliance | Reviews IAM policies, validates RVA rule coverage, defines retention mandates, and approves OAuth client scopes. |
The upgrade happens across 11 sequential stages. The first two establish the foundation (scope and enrichment) before any capability migration begins. The remaining stages migrate access control, observability capabilities, data organization, and configurations.
Before any technical work begins, agree on scope: which teams, applications, and classic assets are in scope, what gets deferred, and what success looks like.
For details, see Upgrade scoping.
With scope defined, enrich all monitored signals with the metadata that IAM, segments, and cost allocation depend on. This stage is iterative: validate coverage, fix gaps, re-validate.
Apply dt.security_context, dt.cost.costcenter, dt.cost.product, and primary_tags.* across all monitored signals. Enrichment coverage must meet the agreed threshold before starting stage 3.
With enrichment in place, you can configure access boundaries and migrate observability capabilities.
Insufficient enrichment at stage 2 results in poorly configured access control, segmentation, and cost allocation across all downstream stages. Validate coverage before proceeding.
For details, see Enrich ingested signals.
Replace classic management zones with segments, which work as global filters across the platform, and with IAM access policies, boundaries, and groups.
For details, see Upgrade management zones to IAM and segments.
Migrate RUM, cloud integrations, classic log settings, and extensions to Latest Dynatrace. Route log ingestion through OpenPipeline and Grail.
For details, see Upgrade observability data and settings.
After observability capabilities are upgraded, assess signal volumes and configure bucket routing if needed. Required before starting stage 6 for high-volume environments.
Assess log and span volumes, design a bucket strategy, and configure OpenPipeline routing to optimize query performance and enforce retention policies.
For details, see Partition data.
With your environment enriched, capabilities upgraded, and data organized, your environment will then be ready for the configuration upgrade phase, in which teams can begin migrating their classic configurations to Latest Dynatrace.
Migrate service naming rules to OpenPipeline, upgrade service detection, replace calculated metrics with DQL-based Grail equivalents, migrate processing rules, rebuild SLOs, and upgrade RVA monitoring rules.
For details, see Upgrade configurations and settings.
Migrate actively used classic dashboards using the built-in converter, then rebuild unconverted tiles and management zone filters manually.
This stage runs in parallel with stage 8. Both must complete before starting stage 9.
For details, see Upgrade dashboards.
Convert classic metric alerts using the built-in tooling, recreate entity-selector-based alerts with DQL, and upgrade maintenance windows.
This stage runs in parallel with stage 7. Both must complete before starting stage 9.
For details, see Upgrade metrics alerting and maintenance windows.
Migrate problem notifications, security notifications, and enterprise integrations (ServiceNow, PagerDuty) to event-driven workflow-based delivery.
For details, see Upgrade team-based and global alerting.
Update DQL queries in dashboards, alerts, and workflows to reference Smartscape 2.0 entity types and relationships after the dashboard and alerting upgrades.
For details, see Upgrade remaining entities and metrics.
Audit classic API usage, create OAuth clients with granular scopes, and migrate CI/CD pipelines and third-party integrations to Latest Dynatrace endpoints.
For details, see Upgrade API and tokens.
Completing all 11 stages means your environment is fully running on Latest Dynatrace. Classic configurations have been migrated or retired, access is governed by IAM boundaries and segments, and all observability signals flow through Grail.
The final step is attribution. The enrichment attributes and data buckets you configured in the early phases now power cost allocation; use them to show each team and cost center exactly what they're consuming.
dt.cost.costcenter or equivalent attributes are correctly applied and bucketedWith cost attribution in place, your upgrade is complete. Use the upgrade overview as an ongoing reference if teams onboard later or if deferred stages are revisited.