dt-upgrade

Dynatrace 升级技能

帮助用户评估并执行 Dynatrace 升级，从经典版／第二代平台概念迁移到第三代平台概念。

概述

Dynatrace 升级会将环境从经典版（第二代）功能迁移到对应的第三代功能。阶段是环境的属性，而非客户的属性：

• 阶段 1 —— 混合默认模式。第二代和第三代 UI 并存，启用经典应用，不移除任何内容。大多数现有客户目前都处于此阶段。
• 阶段 2 —— 仅适用于新环境（SaaS 331+）。移除 32 个经典应用、21 个 API、管理区域和自动标记。无法从阶段 1 原地升级 —— 阶段 2 仅在创建环境时可用。
• 阶段 3 —— 选择加入第二代退役。移除 50 个应用、45 个 API、API 令牌、实体 ID，以及所有剩余的经典概念。针对每个环境，且不可逆 —— 选择加入前必须完成所有迁移。

评估环境前，先确认它所处的阶段。有关完整的阶段详情、移除清单和进入阶段 3 的路径，请参阅 overview.md。

数据类型

评估升级就绪情况时，跟踪数据分为以下类别：

• 经典用量 —— 跟踪旧版功能的单次使用事件（视图、查询、API 调用）
• 经典配置 —— 列出可能需要迁移的经典配置对象
• 就绪状态 —— 针对阶段 3 的逐项通过／失败兼容性检查
• 新版用量 —— 跟踪第三代替代方案的采用情况

操作工作流

此技能将引导用户端到端完成升级：确定范围、制定计划、执行并验证。对于任何会更改租户配置的请求，请遵循以下阶段。

硬性门槛： 在告知用户你的意图并获得用户同意之前，不得向环境写入配置、POST 对象、删除经典对象或开始执行计划。产物的规模会随任务大小而变化，但始终必须获得批准。

先对请求分类，并说明你选择的级别，以便用户提出调整：

• 问题 —— 就绪情况评估或“X 的替代方案是什么”之类的问题。不更改配置。运行相关领域的跟踪查询，报告结果，然后完成。
• 单项任务 —— 范围限定在参考索引中某一项的有限升级任务。提出关键问题，在聊天中说明方案，获得同意后，再使用待办事项列表执行。不需要规格说明或计划文件。
• 项目 —— 涉及三个或更多领域、跨领域更改或完整的租户升级。按以下完整阶段执行，并编写规格说明和计划。

若无法确定应选哪一级，选择较重的一级。执行过程中发现隐藏范围时，应提升级别——说明情况并升级处理。

开始项目级任务前，务必阅读 references/upgrade-workflow.md；需要规格说明模板、计划任务结构或按对象类型划分的验证步骤时，也请阅读此文件。

阶段 1 — 范围

在首次查询前验证访问权限和工具。 运行 dtctl doctor——它会通过一条命令检查配置有效性、当前上下文、环境可达性、令牌获取情况和 API 身份验证。然后确认上下文指向的是预期环境（dtctl config current-context）：针对错误租户执行升级，是此技能可能导致的最严重问题。如果尚未配置 dtctl，请停止并询问要面向哪个环境，而不是根据对话中的 URL 猜测。继续之前，报告你验证了哪些内容，以及所针对的环境。

然后先确定租户上下文并运行发现查询，再提出详细问题：对于没有经典用法的领域，绝不要规划迁移。逐一提出澄清问题，优先采用多项选择。确认哪些对象仍然有用——不再使用的经典配置应删除，而不是迁移。说明范围和方法，然后停止并等待用户明确同意。Program tier 会将规范写入 docs/dt-upgrade/YYYY-MM-DD-<topic>-spec.md，自行审查，并请用户在规划前审阅。

阶段 2 — 规划

每个迁移单元对应一个任务，每项任务都要注明参考文件、确切对象及其依赖项，并以用户可以审阅的内容收尾。步骤要小而明确，写出实际查询和字段映射——“适当映射字段”和“处理边缘情况”属于规划失败，而非具体步骤。对照规范自行审查覆盖范围、占位符和任务顺序，然后保存到 docs/dt-upgrade/YYYY-MM-DD-<topic>-plan.md。

阶段 3 — 执行

严格审阅计划，并在开始前提出顾虑。一次只执行一项任务，每项任务对应一个待办事项，并在任务之间与用户确认进度。遇到任何阻碍都要停止并询问——例如权限缺失、字段没有 gen3 对应项或步骤不明确。绝不要为了继续推进而臆造配置值，也绝不要在确认替代对象正常工作前删除经典对象。

阶段 4 — 验证

先有证据，再作声明。 如果你没有在本条消息中运行检查，就不能说检查通过。使用对象类型支持的所有检查：

1. 与参考文件交叉核对 — 逐字段对照该领域的参考文件检查生成的配置。始终执行。
2. 用户审阅 — 展示配置，并说明你作出的每一项非机械性决定。始终执行。
3. 跟踪查询 — 重新运行该领域的查询并粘贴输出。
4. 写入前验证 — 仅在该领域的参考文档中有说明时执行，并严格使用文档指定的命令。

不要假设存在试运行。 dtctl apply --dry-run 仅为客户端预览：它不会联系 API，却会报告成功，即使架构不存在也一样。对于大多数对象类型，在实际写入前都没有服务器端验证，因此检查 1 和 2 是主要验证方式，而非备用方案。绝不要把客户端解析说成验证；“API 已接受”也不能证明配置实现了经典对象的功能。

阶段 5 — 收尾

重新扫描已涉及领域的就绪情况，然后报告已迁移／剩余／受阻的内容，并附上证据和产物路径，同时提出后续步骤。等待用户选择。

出现故障时

先找出根本原因，再做任何更改：阅读完整错误信息，包括响应正文；重现问题；检查发生了什么变化；并逐字段对比故障对象与正常对象。提出一个假设，测试一项更改。失败三次后就停止，并告知用户——失败三次通常意味着方法不对，而不是第四次修复就能解决问题。

遇到 401 或 403 时，先怀疑凭据，而不是请求。 凭据取决于 API 类型：Platform API（<env>.apps.dynatrace.com/platform/）使用平台令牌（dt0s16.*）或 OAuth；classic API（<env>.live.dynatrace.com/api/）使用访问令牌（dt0c01.*）；Account Management（api.dynatrace.com）两者都不使用——只使用账户 OAuth 客户端凭据换取短时有效（约 5 分钟）的 bearer 令牌。

只有一部分 classic API 会通过 Platform API 代理。dtctl 可通过浏览器登录或平台令牌访问这部分 API；其余 API 没有 dtctl 调用路径——请使用访问令牌直接调用 .live 主机。这是升级工作中的预期情况，并非配置错误。dtctl 不支持 api.dynatrace.com，也完全无法使用账户 OAuth 客户端凭据——它的浏览器登录是另一种流程。

明确指出缺少的具体作用域，并告知用户——凭据缺失是阻塞问题，不能靠重试解决。切勿回显令牌值。请参阅 upgrade-workflow.md，了解 API 类型对照表和分诊表。

存在 Git 时

在执行开始时，检查一次 git rev-parse --is-inside-work-tree。如果不是代码仓库：跳过所有 Git 步骤，且绝不要建议运行 git init。如果是代码仓库：建议创建工作分支，并在每项任务通过验证后提交。绝不推送、绝不创建拉取请求、绝不强制推送——是否与远程仓库集成由用户决定，不属于此技能的范围。

危险信号

想法	实际情况
“映射关系很明显，我直接写配置就行”	这份参考资料之所以存在，就是因为映射关系有例外。每项任务都要阅读。
“他们要求升级，所以批准应用更改了”	批准制定计划不等于批准应用更改。先展示配置。
“API 接受了，所以配置正确”	接受只表示格式正确，并不表示与 classic 对象等效。
“我顺便清理一下 classic 对象”	替代对象尚未验证就删除原对象，后果无法挽回。应拆分为单独任务，并单独获得批准。
“计划内容变多了，不过我快做完了”	隐藏的范围扩大会提高任务等级。应说明情况并提升等级。
“分支检查全绿，我推送吧”	绝不允许。不能推送、不能创建 PR，没有例外。

参考资料索引

通用

文件	说明
overview.md	升级阶段、数据类型、通用先决条件和计划检查清单
upgrade-workflow.md	范围、计划、执行和验证阶段；规范与计划模板；验证检查；凭据和 API 类型分诊；调试；Git 处理

共享

多个升级参考资料都会复用的通用工具。

文件	说明
metric-transpiler.md	通过 /api/v2/metrics/transpile API 将 classic 2G 指标选择器和表达式转换为 Grail DQL

平台

经典概念	Gen3 替代方案	参考资料
Dashboards Classic、Data Explorer、Metrics、Reports	Dashboards、Notebooks	dashboards-classic.md
第 2 代实体查询	Smartscape / 原始数据增强	entity-queries.md
IAM 第 2 代角色	IAM 默认策略	iam-2nd-gen-roles.md
作用域限定为管理区域的第 2 代角色授权	针对增强字段/标签的 IAM 策略，或 Grail 存储桶权限	mz-permission-scopes.md
管理区域	分段 / IAM 策略 / Grail 存储桶	management-zones.md
自动打标	源端 / 集中式 / OpenPipeline 主标签	autotagging.md
自定义设备（实体 API）	Smartscape API	custom-devices.md
SNMP 自定义设备监控；带有 targetFilter（动态实体查找）的 ICMP/TCP MULTI_PROTOCOL 监视器	SNMP 扩展 (com.dynatrace.extension.snmp) 自动发现；使用静态主机目标定位的 NETWORK_AVAILABILITY 监视器（dtctl/Settings API），或带有显式 targetList 的 MULTI_PROTOCOL 监视器（Environment API v2）	custom-devices-synthetic.md
经典告警和问题通知（指标事件、磁盘规则、AWS 异常检测、进程可用性、告警配置文件、通知集成）	基于 DQL 的异常检测器、边缘端检测器、工作流通知	alerting-and-problem-notifications.md
经典管道（日志、业务事件）	OpenPipeline 管道	classic-pipeline.md
经典凭据保险库 API (/api/v2/credentials, @dynatrace-sdk/client-classic-environment-v2)	Platform Credential Vault API (/platform/credential-vault/v1/, @dynatrace-sdk/client-credential-vault)	credential-vault.md

边缘数据平台

经典概念	Gen3 替代方案	参考资料
经典云集成（AWS/Azure/GCP）	Fleet Management App	classic-cloud-integrations.md
网络区域强制执行	--	network-zones.md
ActiveGate 身份验证强制执行（第 3 阶段）	--	activegate-auth-tokens.md
云遥测数据增强	用于摄取数据增强和 Grail 主标签的集中式设置	cloud-telemetry-enrichment.md
Dynatrace Operator（版本、令牌类型、部署模式、操作数构件）	Dynatrace Operator 1.10.0+，搭配 Platform 令牌和受支持的 OneAgent 部署模式	dynatrace-operator.md
低于 Smartscape2 最低版本的 EF2 扩展；低于所需版本或限定为管理区域的监控配置	扩展 OpenPipeline 实体提取（Smartscape2）；监控配置迁移	ef2-entity-extraction.md
DT Plugins（EF1），仅限自定义	通过 Hub 使用 EF2 扩展，或自定义重建	plugins-ef1.md

应用可观测性

经典概念	Gen3 替代方案	参考
Log v2	Grail 上的日志	log-v2.md
经典全服务检测（SDv1）规则	--	classic-service-detection-rules.md
SDv1 全局故障检测规则	--	global-failure-detection-rules.md
请求属性	--	request-attributes.md
全局请求命名规则	--	global-request-naming-rules.md
服务专属请求命名规则	--	service-specific-request-naming-rules.md
计算服务指标	OpenPipeline span 指标提取，可在 span 上表达定义	calculated-service-metrics.md
外部服务（数据库、不透明服务和第三方服务）	服务应用	external-services.md
消息传递／队列和屏幕	--	messaging-queues.md
属性屏蔽配置（OTEL 摄取管道）	--	attribute-masking-configs.md

基础设施可观测性

经典概念	Gen3 替代方案	参考
经典磁盘异常检测	Disk Edge	classic-disk-anomaly-detection.md
经典主机可用性告警（builtin:anomaly-detection.infrastructure-hosts、连接丢失和正常关闭）	使用 Infrastructure & Operations 应用模板创建自定义告警（Phase 3 默认未配置）	classic-host-availability-alerting.md
VMware ActiveGate 集成	VMware Extension	vmware-activegate-integration.md
CloudFoundry ActiveGate 集成	CloudFoundry Extension	cloudfoundry-activegate-integration.md
经典维护窗口	Gen3 维护窗口	classic-maintenance-windows.md
作用于合成监视器的经典维护窗口（实体类型为 SYNTHETIC_TEST、SYNTHETIC_TEST_STEP、HTTP_CHECK、HTTP_CHECK_STEP、SYNTHETIC_LOCATION、EXTERNAL_SYNTHETIC_TEST、EXTERNAL_SYNTHETIC_TEST_STEP）	使用 dt.smartscape.http_monitor、dt.smartscape.browser_monitor、primary_tags.<key>、dt.security_context 或分段筛选器配置 Gen3 维护窗口	classic-maintenance-windows-synthetic.md
经典数据库监控	数据库可观测性	classic-database-monitoring.md
经典网络监控	基础设施可观测性扩展	classic-network-monitoring.md
经典 Windows 服务监控	OS 服务监控	classic-windows-service-monitoring.md
经典 OneAgent 进程连接监控	OneAgent 网络连接监控	classic-process-connection-monitoring.md
Kubernetes 遥测数据增强	集中式增强配置	kubernetes-telemetry-enrichment.md
推断出的主机（容器中的进程，无主机 Agent）	Gen3 无对应方案——以 INFRASTRUCTURE 或 DISCOVERY 模式安装 OneAgent	inferred-hosts.md

云自动化

经典概念	Gen3 替代方案	参考
引用经典 SLO 的 SRG	使用 DQL 目标的 SRG	srg-classic-slo.md

应用安全

经典概念	Gen3 替代方案	参考
Vulnerabilities 应用	更新后的漏洞监控	vulnerabilities-app.md

数字体验

经典概念	Gen3 替代方案	参考
第三方监控集成（POST /api/v1/synthetic/ext/tests）	Grail 原生事件摄取 API（POST /platform/ingest/custom/events/external.tests）	ext-monitors-migration.md
在 Grail 上启用 RUM — 批量启用前端（Web、移动端；清点、分类、启用、验证）	最新版 Dynatrace 上的 RUM	enable-rum-on-grail.md
RUM 异常检测	前端健康警报	rum-anomaly-detection.md
经典操作和会话属性捕获，以及经典用户标记（Web 应用上的用户标记规则）	事件和会话属性捕获、无需配置的属性；用户标记会变为 user.identifier，由 dynatrace.identifyUser() 或 OpenPipeline 规则设置 — Gen3 中没有对应设置	classic-action-session-properties.md