/dt-upgrade

name: dt-upgrade
description: >
  Guide users through Dynatrace upgrade from classic/2nd-gen to 3rd-gen.
  Assess tenant readiness, run tracking queries, identify migration actions
  for dashboards, entity queries, IAM, management zones, OpenPipeline,
  service detection, logs, K8s, RUM, synthetic, alerting.
  Includes cloud integration migration (AWS, Azure, GCP) from classic
  to new (Smartscape on Grail): connection discovery, metric mapping,
  and cutover.
  Keywords: upgrade, migrate, classic, gen3, phase2, phase3, readiness,
  cloud integration, AWS, Azure, GCP, classic connection, new connection,
  Smartscape on Grail, fleet management, Site Reliability Guardian (SRG),
  classic pipeline, log processing pipeline, bizevents pipeline,
  pipeline upgrade, classic processing rules,
  ActiveGate, authToken, auth token,
  DynaKube, dynatrace-operator, classicFullStack, Platform token,
  enable RUM on Grail, RUM migration, mobile RUM, web RUM, Experience Vitals.
license: Apache-2.0

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](references/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.