Dynatrace Upgrade Skill

Help users assess and execute their Dynatrace upgrade from classic/2nd-generation to 3rd-generation platform concepts.

Overview

The Dynatrace upgrade transitions environments from classic (2nd-gen) features to 3rd-generation equivalents. A phase is a property of an environment, not of a customer:

• Phase 1 -- Hybrid default. Gen2 and gen3 UI side by side, classic apps enabled, nothing removed. Where most existing customers are today.
• Phase 2 -- New environments only (SaaS 331+). Removes 32 classic apps, 21 APIs, management zones, and auto-tagging. No in-place upgrade from Phase 1 -- Phase 2 is only available at environment creation.
• Phase 3 -- Opt-in gen2 retirement. Removes 50 apps, 45 APIs, API tokens, entity IDs, and all remaining classic concepts. Per environment and permanent -- everything must be migrated before the opt-in.

Establish which phase an environment is in before assessing it. See overview.md for the full phase detail, removal lists, and the paths into Phase 3.

Data Types

When assessing upgrade readiness, tracking data falls into these categories:

• Classic Usage -- Tracks individual usage events of legacy features (views, queries, API calls)
• Classic Configuration -- Lists classic config objects that may need migration
• Readiness Status -- Per-item pass/fail compatibility check for Phase 3
• New Usage -- Tracks adoption of gen3 replacements

Operating Workflow

This skill drives the upgrade end to end: scope it, plan it, execute it, verify it. Follow the stages below for any request that changes tenant configuration.

Hard gate: do not write a configuration to environment, POST an object, delete a classic object, or start executing a plan until you have told the user what you intend and they have said yes. The artifacts scale with the size of the job. However, the approval is always required.

Classify the request first and say which tier you picked, so the user can override it:

• Question — a readiness assessment or a "what replaces X" question. No configuration changes. Run the area's tracking queries, report findings, done.
• Single task — a limited upgrade task scoped to one item in the Reference Index. Ask the questions that matter, present the approach in chat, get a yes, then execute with a todo list. No spec or plan file.
• Program — three or more areas, a cross-cutting change, or a full tenant upgrade. Full stages below with written spec and plan.

When torn between two tiers, take the heavier one. Discovering hidden scope mid-engagement upgrades the tier — say so and step up.

Read references/upgrade-workflow.md before a Program-tier engagement, and whenever you need the spec template, the plan task structure, or the per-object-type verification steps.

Stage 1 — Scope

Validate access and tooling before the first query. Run dtctl doctor — it checks config validity, current context, environment reachability, token retrieval, and API authentication in one command. Then confirm the context points at the intended environment (dtctl config current-context): running an upgrade against the wrong tenant is the worst failure this skill can cause. If dtctl is not configured, stop and ask which environment to target rather than guessing from a URL in the conversation. Report what you verified, and against which environment, before moving on.

Then establish tenant context and run the discovery queries before asking detailed questions: never plan a migration for an area with no classic usage. Ask clarifying questions one at a time, preferring multiple choice. Establish which objects are still needed at all — abandoned classic config should be deleted, not migrated. Present the scope and approach, then stop and wait for an explicit yes. Program tier writes the spec to docs/dt-upgrade/YYYY-MM-DD-<topic>-spec.md, self-reviews it, and has the user review it before planning.

Stage 2 — Plan

One task per migration unit, each naming its reference file, its exact objects, its dependencies, and ending in something the user can review. Bite-sized steps with the actual queries and field mappings written out — "map the fields appropriately" and "handle edge cases" are plan failures, not steps. Self-review against the spec for coverage, placeholders, and task order, then save to docs/dt-upgrade/YYYY-MM-DD-<topic>-plan.md.

Stage 3 — Execute

Reread the plan critically and raise concerns before starting. One task at a time, one todo per task, checkpoint with the user between tasks. Stop and ask on any blocker — a missing permission, a field with no gen3 equivalent, an unclear step. Never invent a configuration value to keep moving, and never delete a classic object before its replacement is verified working.

Stage 4 — Verify

Evidence before claims. If you have not run the check in this message, you cannot say it passed. Use every check the object type supports:

1. Reference cross-check — walk the generated config field by field against the area's reference file. Always.
2. User review — show the config and name every non-mechanical decision you made. Always.
3. Tracking query — re-run the area's queries and paste the output.
4. Pre-write validation — only where the area's reference documents one, using exactly the command it names.

Do not assume a dry run exists. dtctl apply --dry-run is a client-side preview only: it reports success without contacting the API, even for a schema that does not exist. For most object types there is no server-side validation before the real write, so checks 1 and 2 are the primary verification, not a fallback. Never describe a client-side parse as validation, and "the API accepted it" is not evidence that the config does what the classic object did.

Stage 5 — Wrap up

Re-run the readiness scan for the areas touched, then report migrated / remaining / blocked with the evidence and the artifact paths, and offer the next steps. Wait for the user to choose.

When something breaks

Find the root cause before changing anything: read the full error including the response body, reproduce it, check what changed, and compare the broken object against a working one field by field. Form one hypothesis, test one change. After three failed attempts, stop and bring it to the user — three failures usually means the approach is wrong, not that the fourth fix is the right one.

On 401 or 403, suspect the credential before the request. The surface decides the credential: Platform API (<env>.apps.dynatrace.com/platform/) takes a platform token (dt0s16.*) or OAuth; classic API (<env>.live.dynatrace.com/api/) takes an access token (dt0c01.*); Account Management (api.dynatrace.com) takes neither — only account OAuth client credentials exchanged for a short-lived (~5 min) bearer.

Only a subset of classic APIs is proxied through the Platform API. dtctl reaches that subset via browser login or a platform token; for the rest there is no dtctl path — call the .live host directly with an access token. That is expected in upgrade work, not a misconfiguration. dtctl does not support api.dynatrace.com and cannot use account OAuth client credentials at all — its browser login is a different flow entirely.

Name the exact missing scope and hand it back to the user — a credential gap is a blocker, not something to retry. Never echo a token value. See upgrade-workflow.md for the surface map and triage table.

Git, when present

Check git rev-parse --is-inside-work-tree once, at the start of execution. Not a repository: skip all git steps and never suggest git init. A repository: offer a working branch, and commit after each task passes verification. Never push, never open a pull request, never force-push — integration with a remote is the user's decision, outside this skill.

Red flags

Reference Index

General

Shared

Cross-cutting utilities reused by multiple upgrade references.

Platform

Edge Data Platform

Application Observability

Infrastructure Observability

Cloud Automations

Application Security

Digital Experience