dt-migration

Smartscape 移行スキル

このスキルでは、Dynatrace のクラシックおよび Gen2 のエンティティベースの DQL クエリとクエリパターンを、Smartscape ベースの同等のものに移行します。

最終的な DQL を記述する前に dt-dql-essentials スキルを読み込み、変換後のクエリが現在の DQL 構文規則にも従うようにしてください。

このスキルでは、Smartscape を中心とした DQL の移行のみを扱います。アセットレベルの移行ワークフローは対象外です。

クエリの目的の分類

まずここから始めてください。 適切な移行戦略は、クエリで使用されているクラシック構文だけでなく、クエリが実際に何をしようとしているかによって決まります。

状況は次の 3 つに分類されます。

#	状況	クラシックなアンチパターン	移行戦略
1	エンティティ条件でフィルタリングする大量データクエリ	時系列、ログ、またはメトリクスのクエリの 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 ワークロードノードタイプ	複数のワークロードタイプにマッピングされます。cloud-application guide を読み込んでください
dt.entity.cloud_application_instance	dt.smartscape.k8s_pod	K8S_POD	Classic のクラウドアプリケーションインスタンスはポッドになります
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	2 つの並列配列は 1 つのレコード配列に置き換わります。各レコードには 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 — 移行前後の例