dt-migration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Smartscape Migration Skill

Smartscape迁移技能

This skill helps migrate Dynatrace classic and Gen2 entity-based DQL queries and query patterns to Smartscape-based equivalents.

Use it to:

convert classic entity types to Smartscape node types
rewrite classic entity DQL into Smartscape DQL

migrate

entityName()

entityAttr()

classicEntitySelector()

, and classic relationship patterns

explain how classic entity concepts map to Smartscape nodes, edges, fields, and IDs

Load the dt-dql-essentials skill before writing final DQL so the translated query also follows current DQL syntax rules.

This skill focuses on Smartscape-oriented DQL migration only. It does not cover asset-level migration workflows.

本技能可帮助将Dynatrace经典版和第二代（Gen2）基于实体的DQL查询及查询模式迁移为基于Smartscape的等效方案。

适用场景：

将经典实体类型转换为Smartscape节点类型
将经典实体DQL重写为Smartscape DQL

迁移

entityName()

、

entityAttr()

、

classicEntitySelector()

及经典关联关系模式

解释经典实体概念如何映射到Smartscape的节点、边、字段和ID

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

本技能仅专注于面向Smartscape的DQL迁移，不涵盖资产级别的迁移工作流。

Use Cases

用例

Load this skill when the user wants to:

Use case	What to do
Convert a classic entity query to Smartscape	Follow the migration workflow, use the mapping table, then load the relevant detailed references
Migrate `classicEntitySelector(...)` to Smartscape	Start from the constrained side, convert selector filters to node filters, and replace relationship selectors with `traverse`
Understand what a classic entity became in Smartscape	Check the entity mapping table and special cases before translating literally
Rewrite classic DQL functions such as `entityName()` or `entityAttr()`	Use the DQL construct guidance and function migration reference
Migrate classic topology navigation	Replace relationship fields and selectors with `smartscapeNodes` , `smartscapeEdges` , `traverse` , or `references`
Translate signal or event queries using `dt.entity.*` dimensions	Rewrite every entity dimension to the correct `dt.smartscape.*` field and adjust related helpers

当用户有以下需求时加载本技能：

用例	操作指引
将经典实体查询转换为Smartscape版本	遵循迁移工作流，使用映射表，然后加载相关的详细参考文档
将 `classicEntitySelector(...)` 迁移到Smartscape	从约束侧开始，将选择器过滤器转换为节点过滤器，并用 `traverse` 替换关联关系选择器
了解经典实体在Smartscape中对应的内容	直译前先查看实体映射表和特殊情况说明
重写 `entityName()` 或 `entityAttr()` 等经典DQL函数	参考DQL结构指引和函数迁移参考文档
迁移经典拓扑导航功能	用 `smartscapeNodes` 、 `smartscapeEdges` 、 `traverse` 或 `references` 替换关联关系字段和选择器
转换使用 `dt.entity.*` 维度的信号或事件查询	将每个实体维度重写为正确的 `dt.smartscape.*` 字段，并调整相关辅助工具

Migration Workflow

迁移工作流

Follow this order:

Identify the classic input pattern:
- ```
fetch dt.entity.*
```
- ```
classicEntitySelector(...)
```
- relationship field access such as
```
belongs_to[...]
```
  ,
```
runs[...]
```
  ,
```
instance_of[...]
```
- signal or event queries using
```
dt.entity.*
```
Identify the involved classic entity types.
Look up the Smartscape replacement in the core entity mapping table below.
Check which classic DQL constructs need explicit migration.

Rewrite the query using Smartscape primitives:

```
smartscapeNodes
```
```
smartscapeEdges
```
```
traverse
```
```
references
```
```
getNodeName()
```
```
getNodeField()
```

Check for special cases, unsupported entities, or ID assumptions.
Load the matching detailed references for the specific entity family or migration pattern.

For the full migration process and output expectations, load references/migration-workflow.md.

遵循以下顺序：

识别经典输入模式：
- ```
fetch dt.entity.*
```
- ```
classicEntitySelector(...)
```
- 关联关系字段访问，例如
```
belongs_to[...]
```
  、
```
runs[...]
```
  、
```
instance_of[...]
```
- 使用
```
dt.entity.*
```
  的信号或事件查询
识别涉及的经典实体类型。
在下方的核心实体映射表中查找对应的Smartscape替代项。
确认哪些经典DQL结构需要显式迁移。

使用Smartscape原语重写查询：

```
smartscapeNodes
```
```
smartscapeEdges
```
```
traverse
```
```
references
```
```
getNodeName()
```
```
getNodeField()
```

检查是否存在特殊情况、不支持的实体或ID假设。
加载对应特定实体族或迁移模式的详细参考文档。

完整的迁移流程和输出预期，请加载references/migration-workflow.md查看。

Core Entity Mapping Table

核心实体映射表

Use this compact table first for common migrations. For the full mapping set, load references/type-mappings.md.

Classic / Gen2 entity	Smartscape field	Smartscape node type	Notes
`dt.entity.host`	`dt.smartscape.host`	`HOST`	Standard host mapping
`dt.entity.service`	`dt.smartscape.service`	`SERVICE`	Standard service mapping
`dt.entity.process_group_instance`	`dt.smartscape.process`	`PROCESS`	Process instance maps directly
`dt.entity.container_group_instance`	`dt.smartscape.container`	`CONTAINER`	Container-group instance maps directly
`dt.entity.kubernetes_cluster`	`dt.smartscape.k8s_cluster`	`K8S_CLUSTER`	Kubernetes cluster
`dt.entity.kubernetes_node`	`dt.smartscape.k8s_node`	`K8S_NODE`	Kubernetes node
`dt.entity.kubernetes_service`	`dt.smartscape.k8s_service`	`K8S_SERVICE`	Kubernetes service
`dt.entity.cloud_application`	multiple workload fields	multiple K8S workload node types	Maps to multiple workload types; load the cloud-application guide
`dt.entity.cloud_application_instance`	`dt.smartscape.k8s_pod`	`K8S_POD`	Classic cloud app instance becomes pod
`dt.entity.cloud_application_namespace`	`dt.smartscape.k8s_namespace`	`K8S_NAMESPACE`	Namespace mapping
`dt.entity.application`	`dt.smartscape.frontend`	`FRONTEND`	Frontend application mapping
`dt.entity.aws_lambda_function`	`dt.smartscape.aws.lambda_function`	`AWS_LAMBDA_FUNCTION`	Cloud-function entity mapping

通用迁移请优先使用这个精简表。完整映射集请加载references/type-mappings.md查看。

经典/第二代实体	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`	经典云应用实例对应为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 Constructs to Inspect During Migration

迁移期间需要检查的DQL结构

These classic constructs usually need explicit rewriting:

Classic construct	Typical Smartscape replacement	Notes
`entityName(x)`	`name` or `getNodeName(x)`	Prefer `name` when querying nodes directly
`entityAttr(x, "...")`	direct node field or `getNodeField(x, "...")`	Prefer direct fields when available
`classicEntitySelector(...)`	node filters plus `traverse`	Start from the constrained side
`dt.entity.*` in signal queries	`dt.smartscape.*`	Applies to `by` , `filter` , `fieldsAdd` , `expand` , and related clauses
`belongs_to[...]` , `runs[...]` , `instance_of[...]`	`traverse` or `references[...]`	`references` works only for static edges
classic entity ID filters	Smartscape `id`	Do not reuse classic IDs blindly
`affected_entity_ids` and `affected_entity_types`	`smartscape.affected_entity.ids` and `smartscape.affected_entity.types`	Use Smartscape event fields

For the detailed function-by-function guide, load references/dql-function-migration.md.

这些经典结构通常需要显式重写：

经典结构	常用Smartscape替代项	说明
`entityName(x)`	`name` 或 `getNodeName(x)`	直接查询节点时优先使用 `name`
`entityAttr(x, "...")`	直接节点字段或 `getNodeField(x, "...")`	存在直接字段时优先使用
`classicEntitySelector(...)`	节点过滤器加 `traverse`	从约束侧开始
信号查询中的 `dt.entity.*`	`dt.smartscape.*`	适用于 `by` 、 `filter` 、 `fieldsAdd` 、 `expand` 及相关子句
`belongs_to[...]` 、 `runs[...]` 、 `instance_of[...]`	`traverse` 或 `references[...]`	`references` 仅适用于静态边
经典实体ID过滤器	Smartscape `id`	不要盲目复用经典ID
`affected_entity_ids` 和 `affected_entity_types`	`smartscape.affected_entity.ids` 和 `smartscape.affected_entity.types`	使用Smartscape事件字段

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

Special Cases

特殊情况

Do not translate these patterns literally:

Host group — no standalone Smartscape entity; use fields on
```
HOST
```
Process group — no standalone Smartscape entity; use fields on
```
PROCESS
```
Container group — no standalone Smartscape entity; preserve output shape with placeholders if needed
Classic IDs — classic entity IDs do not carry over to Smartscape automatically
Planned, missing, or not-planned mappings — check the full mapping table before assuming direct support

Load references/special-cases.md before migrating these patterns.

不要直译以下模式：

主机组 — 没有独立的Smartscape实体；使用
```
HOST
```
上的字段
进程组 — 没有独立的Smartscape实体；使用
```
PROCESS
```
上的字段
容器组 — 没有独立的Smartscape实体；必要时使用占位符保留输出结构
经典ID — 经典实体ID不会自动同步到Smartscape
规划中、缺失或未规划的映射 — 假设直接支持前请先查看完整映射表

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

Entity-Focused Guides

实体专属指南

When a migration centers on a specific entity family, load the matching detailed guide:

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

Each guide explains:

what the classic entity represented
what the Smartscape replacement is
which fields usually change
how relationships are migrated
common examples and pitfalls

当迁移聚焦于特定实体族时，加载对应的详细指南：

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

参考文档

references/README.md — Reference index and reading guide
references/migration-workflow.md — End-to-end migration process and output expectations
references/type-mappings.md — Full classic-to-Smartscape type and field mappings
references/dql-function-migration.md — How to migrate classic DQL functions and patterns
references/relationship-mappings.md — Valid Smartscape edges and traversal guidance
references/special-cases.md — Non-literal and unsupported entity migrations
references/quick-reference.md — Compact rules and gotchas
references/examples.md — Before/after migration examples

references/README.md — 参考索引和阅读指南
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 — 迁移前后对比示例