dt-migration

Smartscape 迁移技能

此技能可将 Dynatrace 经典版和 Gen2 基于实体的 DQL 查询及查询模式迁移为基于 Smartscape 的等效形式。

编写最终 DQL 前，请先加载 dt-dql-essentials 技能，确保迁移后的查询也符合当前 DQL 语法规则。

此技能仅关注面向 Smartscape 的 DQL 迁移，不涵盖资产级迁移工作流。

查询用途分类

从这里开始。 正确的迁移策略取决于查询的实际用途，而不仅仅是它使用了哪些经典版构造。

有三种不同的情况：

#	情况	经典版反模式	迁移策略
1	按实体条件筛选海量数据的查询	在 timeseries、logs 或 metrics 查询的 filter: 中内联使用 classicEntitySelector(...)	先将实体条件解析为原始数据维度。Smartscape 是备用方案，而非默认方案。
2	使用实体子查询进行筛选的海量数据查询	在 in [...]、lookup [...] 或 join [...] 中使用 fetch dt.entity.*，以筛选外层海量数据查询	采用相同的维度优先策略。改写为原始维度筛选，或 in [smartscapeNodes ...] 子查询。
3	纯实体列表查询	独立使用 fetch dt.entity.*，或将其用作主要结果来源	smartscapeNodes 是唯一有效路径。不存在原始维度替代方案。

决策：

• 情况 1 或 2 — 加载 references/mass-data-filtering-strategy.md，并完成所有步骤，包括字段发现（步骤 2）和等效性验证（步骤 4）。不要跳过 fieldsSnapshot 检查点——它们决定了哪些方法可行。只有在需要实体类型映射或关系遍历来完成 Smartscape 子查询时，才使用下方的迁移工作流作为备用方案。
• 情况 3 — 继续使用下方的迁移工作流和实体映射表。

注意：情况 3 有一种子情况，即使用 classicEntitySelector 筛选 fetch dt.entity.* 返回的实体。这种情况很少见，且同样遵循 smartscapeNodes 路径——先使用 references/mass-data-filtering-strategy.md 的步骤 1B 解析选择器条件，再将其作为节点筛选条件应用于 smartscapeNodes。

迁移工作流

对于情况 3（纯实体列表查询），以及为情况 1 和 2 构造 Smartscape 子查询时，请按以下顺序操作：

1. 确定经典版输入模式：
   • fetch dt.entity.*
   • classicEntitySelector(...)
   • belongs_to[...]、runs[...]、instance_of[...] 等关系字段访问
   • 使用 dt.entity.* 的信号或事件查询
2. 确定涉及的经典版实体类型。
3. 在下方的核心实体映射表中查找 Smartscape 替代方案。
4. 检查哪些经典版 DQL 构造需要显式迁移。
5. 使用 Smartscape 基元重写查询：
   • smartscapeNodes
   • smartscapeEdges
   • traverse
   • references
   • getNodeName()
   • getNodeField()
6. 检查特殊情况、不支持的实体或 ID 假设。
7. 加载与特定实体系列或迁移模式匹配的详细参考资料。

如需完整的迁移流程和输出要求，请加载 references/migration-workflow.md。

核心实体映射表

常见迁移可先使用此精简表。完整映射集请加载 references/type-mappings.md。

Classic / Gen2 实体	Smartscape 字段	Smartscape 节点类型	备注
dt.entity.host	dt.smartscape.host	HOST	标准主机映射
dt.entity.service	dt.smartscape.service	SERVICE	标准服务映射
dt.entity.process_group_instance	dt.smartscape.process	PROCESS	进程实例直接映射
dt.entity.container_group_instance	dt.smartscape.container	CONTAINER	容器组实例直接映射
dt.entity.kubernetes_cluster	dt.smartscape.k8s_cluster	K8S_CLUSTER	Kubernetes 集群
dt.entity.kubernetes_node	dt.smartscape.k8s_node	K8S_NODE	Kubernetes 节点
dt.entity.kubernetes_service	dt.smartscape.k8s_service	K8S_SERVICE	Kubernetes 服务
dt.entity.cloud_application	多个工作负载字段	多种 K8S 工作负载节点类型	映射到多种工作负载类型；请加载云应用指南
dt.entity.cloud_application_instance	dt.smartscape.k8s_pod	K8S_POD	Classic 云应用实例转换为 Pod
dt.entity.cloud_application_namespace	dt.smartscape.k8s_namespace	K8S_NAMESPACE	命名空间映射
dt.entity.application	dt.smartscape.frontend	FRONTEND	前端应用映射
dt.entity.aws_lambda_function	dt.smartscape.aws.lambda_function	AWS_LAMBDA_FUNCTION	云函数实体映射

迁移期间需检查的 DQL 结构

这些 Classic 结构通常需要显式改写：

Classic 结构	常见 Smartscape 替代项	备注
entityName(x)	name 或 getNodeName(x)	直接查询节点时优先使用 name
entityAttr(x, "...")	直接使用节点字段或 getNodeField(x, "...")	有可用的直接字段时优先使用
classicEntitySelector(...)	节点筛选条件加 traverse	从受限的一侧开始；大规模数据查询请先参阅 mass-data-filtering-strategy.md
信号查询中的 dt.entity.*	dt.smartscape.*	适用于 by、filter、fieldsAdd、expand 及相关子句
belongs_to[...]、runs[...]、instance_of[...]	traverse 或 references[...]	references 仅适用于静态边
Classic 实体 ID 筛选条件	Smartscape id	不要盲目复用 Classic ID
affected_entity_ids 和 affected_entity_types	smartscape.affected_entities	一个记录数组取代两个并行数组；每条记录包含 id、type 和 name

按函数逐项查看详细指南，请加载 references/dql-function-migration.md。

特殊情况

不要照字面翻译以下模式：

• 主机组 — 没有独立的 Smartscape 实体；请使用 HOST 上的字段
• 进程组 — 没有独立的 Smartscape 实体；请使用 PROCESS 上的字段
• 容器组 — 没有独立的 Smartscape 实体；如有需要，请使用占位符保留输出结构
• Classic ID — Classic 实体 ID 不会自动沿用到 Smartscape
• 计划中、缺失或未计划的映射 — 假定直接支持前，请先检查完整映射表

迁移这些模式前，请加载 references/special-cases.md。

按实体分类的指南

如果迁移围绕某一特定实体系列展开，请加载相应的详细指南：

• references/entity-host.md
• references/entity-service.md
• references/entity-process.md
• references/entity-container.md
• references/entity-kubernetes.md
• references/entity-cloud-application.md

每份指南都会说明：

• 经典实体所表示的内容
• Smartscape 中的替代对象
• 通常会变化的字段
• 如何迁移关系
• 常见示例和注意事项

参考资料

• references/README.md — 参考资料索引和阅读指南
• references/mass-data-filtering-strategy.md — 情形 1 和 2 请从这里开始。 必须执行的步骤：解析条件、运行 fieldsSnapshot 发现、选择方法、编写查询、验证等效性
• references/auto-tagging-field-mapping.md — 将自动标记规则条件键映射到语义字典字段（海量数据和 Smartscape 节点属性）
• references/entity-selector-predicates.md — classicEntitySelector 表达式的完整谓词词汇
• references/migration-workflow.md — 端到端迁移流程和输出要求
• references/type-mappings.md — 完整的经典类型和字段到 Smartscape 的映射
• references/dql-function-migration.md — 如何迁移经典 DQL 函数和模式
• references/relationship-mappings.md — 有效的 Smartscape 边和遍历指南
• references/special-cases.md — 非字面量和不受支持的实体迁移
• references/quick-reference.md — 简明规则和注意事项
• references/examples.md — 迁移前后示例