dt-upgrade

Dynatrace アップグレードスキル

Dynatrace をクラシック／第 2 世代から第 3 世代のプラットフォーム概念へアップグレードする方法の評価と実行を支援します。

概要

Dynatrace のアップグレードでは、環境をクラシック（第 2 世代）の機能から第 3 世代の同等機能へ移行します。フェーズは顧客ではなく環境のプロパティです。

• フェーズ 1 -- ハイブリッドのデフォルトです。第 2 世代と第 3 世代の UI が並存し、クラシックアプリが有効で、何も削除されません。既存顧客の大半は現在このフェーズです。
• フェーズ 2 -- 新しい環境のみ（SaaS 331 以降）。32 個のクラシックアプリ、21 個の API、管理ゾーン、自動タグ付けが削除されます。フェーズ 1 からのインプレースアップグレードはできません -- フェーズ 2 は環境の作成時にのみ利用できます。
• フェーズ 3 -- オプトインによる第 2 世代の廃止です。50 個のアプリ、45 個の API、API トークン、エンティティ ID、および残りすべてのクラシック概念が削除されます。環境ごとに適用され、元に戻せません -- オプトインする前にすべてを移行する必要があります。

評価を始める前に、環境がどのフェーズにあるかを確認してください。各フェーズの詳細、削除対象の一覧、フェーズ 3 への移行経路については、overview.md を参照してください。

データの種類

アップグレードの準備状況を評価する際、追跡データは次のカテゴリに分類されます。

• クラシックの使用状況 -- レガシー機能（ビュー、クエリ、API 呼び出し）の個々の使用イベントを追跡します
• クラシック設定 -- 移行が必要な可能性のあるクラシック設定オブジェクトを一覧表示します
• 準備状況ステータス -- フェーズ 3 との互換性を項目ごとに合格／不合格で確認します
• 新機能の使用状況 -- 第 3 世代の代替機能の採用状況を追跡します

作業ワークフロー

このスキルでは、対象範囲の特定、計画、実行、検証まで、アップグレードを最初から最後まで進めます。テナントの設定を変更するあらゆるリクエストでは、以下のステージに従ってください。

必須の承認手順： ユーザーに意図を伝え、承認を得るまでは、環境への設定の書き込み、オブジェクトの POST、クラシックオブジェクトの削除、計画の実行を開始してはいけません。成果物の規模は作業の大きさに応じて変わります。ただし、常に承認が必要です。

まずリクエストを分類し、選んだティアをユーザーに伝えてください。ユーザーはその分類を変更できます。

• 質問 — 準備状況の評価、または「X の代わりになるものは何ですか」という質問です。設定の変更はありません。該当領域の追跡クエリを実行し、調査結果を報告したら完了です。
• 単一タスク — Reference Index の項目 1 つを対象とする、範囲の限られたアップグレードタスクです。重要な点を確認し、チャットで進め方を提示して、承認を得てから、ToDo リストに沿って実行してください。仕様書や計画ファイルは不要です。
• プログラム — 3 つ以上の領域に関わる変更、複数領域にまたがる変更、またはテナント全体のアップグレードです。書面の仕様書と計画を含む、以下の全ステージを実施してください。

2 つのティアのどちらにするか迷った場合は、より重い方を選んでください。対応中に隠れた作業範囲が判明した場合は、ティアを引き上げてください。その旨を伝えて、より高いティアに移行します。

プログラムティアの作業に着手する前に、また仕様書テンプレート、計画のタスク構成、オブジェクトの種類ごとの検証手順が必要なときは、references/upgrade-workflow.md を読んでください。

ステージ 1 — 範囲の確認

最初のクエリを実行する前に、アクセスとツールを確認します。 dtctl doctor を実行します。このコマンドで、設定の有効性、現在のコンテキスト、環境への到達性、トークンの取得、API 認証をまとめて確認できます。次に、コンテキストが 意図した 環境を指していることを確認します（dtctl config current-context）。間違ったテナントに対してアップグレードを実行することは、このスキルで起こりうる最悪の失敗です。dtctl が設定されていない場合は、会話中の URL から推測せず、対象の環境を尋ねて作業を中断します。先に進む前に、確認した内容と対象の環境を報告します。

テナントのコンテキストを確立し、詳細な質問をする前に調査クエリを実行します。classic の使用実績がない領域の移行は、決して計画しないでください。確認の質問は一度に一つずつ、選択式を優先して尋ねます。そもそもまだ必要なオブジェクトを特定します。使われなくなった classic 設定は移行するのではなく、削除する必要があります。対象範囲とアプローチを提示したら、明示的な「はい」を得るまで停止して待ちます。Program ティアでは、仕様を docs/dt-upgrade/YYYY-MM-DD-<topic>-spec.md に書き込み、自己レビューしたうえで、計画に進む前にユーザーにレビューしてもらいます。

ステージ 2 — 計画

移行単位ごとにタスクを一つ作成し、それぞれに参照ファイル、対象オブジェクト、依存関係を明記して、ユーザーがレビューできる成果物で終わるようにします。各ステップは細分化し、実際のクエリとフィールドのマッピングを明記します。「フィールドを適切にマッピングする」「エッジケースに対処する」は、計画の不備であり、ステップではありません。仕様に照らして、網羅性、プレースホルダー、タスクの順序を自己レビューし、docs/dt-upgrade/YYYY-MM-DD-<topic>-plan.md に保存します。

ステージ 3 — 実行

計画を批判的に読み直し、開始前に懸念事項を提示します。一度に一つのタスクだけを進め、タスクごとに ToDo を一つ作成し、タスク間でユーザーと確認します。阻害要因があれば、どんな場合でも停止して尋ねます。権限の不足、gen3 に相当するフィールドがない場合、不明瞭な手順などが該当します。作業を進めるために設定値を決して捏造せず、置き換え先が動作することを確認する前に classic オブジェクトを削除してはいけません。

ステージ 4 — 検証

主張する前に、証拠を確認します。 このメッセージでチェックを実行していない場合、合格したとは言えません。オブジェクトの種類が対応するチェックをすべて使います。

1. 参照情報との照合 — 生成した設定を、領域の参照ファイルとフィールドごとに照合します。必ず実施します。
2. ユーザーレビュー — 設定を提示し、行った機械的でない判断をすべて明示します。必ず実施します。
3. 追跡クエリ — 領域のクエリを再実行し、出力を貼り付けます。
4. 書き込み前の検証 — 領域の参照情報に記載されている場合に限り、記載されたコマンドをそのまま使います。

ドライランがあると決めつけてはいけません。 dtctl apply --dry-run はクライアント側のプレビューにすぎません。存在しないスキーマに対しても、API に接続せず成功を報告します。ほとんどのオブジェクトの種類では、実際に書き込む前にサーバー側で検証する方法がありません。そのため、チェック 1 と 2 が補助的な手段ではなく、主な検証方法です。クライアント側の解析を検証と表現してはいけません。また、「API に受け付けられた」ことは、その設定が classic オブジェクトと同じ動作をする証拠にはなりません。

ステージ 5 — 完了

変更した領域の準備状況を再スキャンし、証拠と成果物のパスを添えて、移行済み／残り／ブロック中を報告し、次のステップを提示します。ユーザーが選択するまで待ちます。

問題が発生した場合

変更を加える前に根本原因を特定します。レスポンスボディを含めてエラー全体を読み、再現し、何が変わったかを確認して、問題のあるオブジェクトと正常に動作するオブジェクトを項目ごとに比較します。仮説を1つ立て、変更を1つ試します。3回失敗したら中断し、ユーザーに伝えてください。3回失敗した場合、たいていは4つ目の修正が正解なのではなく、アプローチが間違っています。

401 または 403 の場合、リクエストより先に認証情報を疑ってください。 認証情報は接続先によって異なります。Platform API（<env>.apps.dynatrace.com/platform/）には、プラットフォームトークン（dt0s16.*）または OAuth を使用します。クラシック API（<env>.live.dynatrace.com/api/）にはアクセストークン（dt0c01.*）を使用します。Account Management（api.dynatrace.com）ではどちらも使用せず、アカウント OAuth クライアント認証情報のみを使用し、有効期間の短い（約5分）ベアラーに交換します。

Platform API 経由でプロキシされるクラシック API は一部のみです。dtctl はブラウザーログインまたはプラットフォームトークンを使って、その一部にアクセスします。それ以外には dtctl を使う方法がないため、アクセストークンを使って .live ホストを直接呼び出してください。これはアップグレード作業では想定内であり、設定ミスではありません。dtctl は api.dynatrace.com に対応しておらず、アカウント OAuth クライアント認証情報も一切使用できません。ブラウザーログインはまったく別のフローです。

不足しているスコープを正確に特定してユーザーに伝えてください。認証情報の不足はブロッカーであり、再試行するものではありません。トークンの値を決して表示しないでください。接続先の対応表とトリアージ表については、upgrade-workflow.md を参照してください。

Git が使える場合

実行開始時に一度だけ git rev-parse --is-inside-work-tree を確認します。リポジトリではない場合は、Git 関連の手順をすべて省略し、git init を提案してはいけません。リポジトリの場合は作業ブランチを提案し、各タスクの検証に合格した後でコミットします。プッシュ、プルリクエストの作成、強制プッシュは決して行わないでください。リモートとの統合はユーザーが決めることであり、このスキルの対象外です。

注意すべき兆候

考え	実態
「マッピングは明らかだから、設定をそのまま書けばいい」	このリファレンスがあるのは、マッピングに例外があるためです。タスクごとに読みましょう。
「アップグレードを頼まれたのだから、適用してよい」	計画の承認は適用の承認ではありません。先に設定を見せてください。
「API が受け付けたのだから、正しい」	受け付けられたということは形式が正しいだけで、クラシックオブジェクトと同等とは限りません。
「ついでにクラシックオブジェクトを整理しよう」	置き換えが検証される前に削除すると、元に戻せなくなります。別のタスクとして扱い、別途承認を得てください。
「計画が膨らんだけれど、もうすぐ終わる」	隠れたスコープによってティアが変わります。そのことを伝え、ティアを引き上げてください。
「ブランチが正常だから、プッシュしよう」	決してしないでください。プッシュも PR も不可で、例外はありません。

リファレンス一覧

一般

ファイル	説明
overview.md	アップグレードのフェーズ、データ型、一般的な前提条件、計画チェックリスト
upgrade-workflow.md	スコープ／計画／実行／検証の各段階、仕様と計画のテンプレート、検証チェック、認証情報と API 接続先のトリアージ、デバッグ、Git の扱い

共通

複数のアップグレードリファレンスで再利用される横断的なユーティリティです。

ファイル	説明
metric-transpiler.md	/api/v2/metrics/transpile API を使って、クラシック 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
Management Zones	Segments／IAM ポリシー／Grail バケット	management-zones.md
Autotagging	ソース側／一元管理／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
クラシックパイプライン（Logs、Business events）	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（バージョン、トークンタイプ、デプロイモード、オペランドアーティファクト）	Platform トークンとサポート対象の OneAgent デプロイモードを使用する Dynatrace Operator 1.10.0+	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 のスパンメトリクス抽出	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
従来のデータベースモニタリング	Database Observability	classic-database-monitoring.md
従来のネットワークモニタリング	Infrastructure Observability 拡張機能	classic-network-monitoring.md
従来の Windows サービスモニタリング	OS Services モニタリング	classic-windows-service-monitoring.md
従来の OneAgent プロセス接続モニタリング	OneAgent ネットワーク接続モニタリング	classic-process-connection-monitoring.md
Kubernetes テレメトリーのエンリッチメント	集中管理されたエンリッチメント設定	kubernetes-telemetry-enrichment.md
推定ホスト（コンテナ内プロセス、ホストエージェントなし）	Gen3 に相当するものはありません — OneAgent を INFRASTRUCTURE または DISCOVERY モードでインストールしてください	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