dtctl

dtctl による Dynatrace の操作

Dynatrace 用の kubectl 形式の CLI、dtctl を操作します。形式は dtctl <verb> <resource> [flags] です。

初期化

コンテキスト、権限、コマンドカタログを設定するため、最初に一度だけ実行します。

dtctl commands                          # compact overview: verbs, resources, subcommands (TOON default)
# dtctl commands --brief                 # + mutating/access/scopes + flag types
# dtctl commands --full                  # exhaustive catalog: descriptions, flag defaults, global flags
dtctl config current-context            # active context
dtctl config describe-context $(dtctl config current-context) --plain  # env URL + safety level
dtctl auth status --plain               # token type (OAuth vs API/platform) + safety level
dtctl inventory                         # what data exists HERE: fetchable objects, buckets, entity census, capabilities

安全性レベル：readonly、readwrite-mine、readwrite-all、dangerously-unrestricted。

dtctl commands は「何を実行できますか？」に答え、dtctl inventory は「クエリ対象として何がありますか？」に答えます。探索的な DQL を実行する前に dtctl inventory を実行してください。カタログ内のオブジェクトを取得可能なものとクエリ専用のものに分類します（fetch metrics や fetch smartscape.* は決して実行しないでください）。また、機能の有無を、利用可能、利用不可（確認した根拠も示します。再確認せず、その根拠を引用してください）、不明（判定なし。利用不可の根拠にはなりません）として報告します。組織固有の機能定義を指定するには、--definitions file.yaml を使用します。

接続確認に dtctl auth whoami を使わないでください。このコマンドには app-engine:apps:run 権限を持つ OAuth トークンが必要です。通常の API トークンや読み取り専用スコープのトークンでは、読み取りが機能していても誤って 403 を返します。実際の get／query で確認してください。

DQL（必読）

DQL（dtctl query、dtctl wait query、クエリファイル）を記述、変更、実行する前に、references/DQL-reference.md を確認し、推測や記憶よりもその内容に従ってください。

dtctl query "fetch logs | filter status='ERROR' | limit 100" -o json --plain
dtctl query -f query.dql --set host=h-123 --set timerange=2h -o json --plain   # Go-template vars
dtctl wait query "fetch spans | filter test_id='test-123'" --for=count=1 --timeout 5m
dtctl query "timeseries avg(dt.host.cpu.usage)" -o chart --plain

課金対象の fetch（ログ、イベント、ビジネスイベント、スパン）はスキャンしたバイト数に応じて課金され、ダッシュボードのタイルは更新のたびに再課金されます。DQL を出力する前に references/DQL-reference.md の「Scan Cost」を読み、PARTIAL またはサンプリングされた結果は不完全なものとして扱ってください。

dtctl がインストールされていない、または正常に動作しない場合は、references/troubleshooting.md を参照してください。

関連スキル（AI 向け Dynatrace）

このスキルでは dtctl の操作を扱います。Dynatrace for AI スキルパックでは、ドメイン知識が追加されます。内容は、dt-dql-essentials（DQL の構文、落とし穴、クエリの最適化）、dt-obs-*（ログ、問題、サービス、トレーシング、ホスト、Kubernetes、フロントエンド、AWS／Azure／GCP）、および dt-app-dashboards／dt-app-notebooks です。これらが読み込まれている場合は、何をクエリするかの判断に使用し、実行には dtctl を使用してください。読み込まれていない場合は、npx skills add dynatrace/dynatrace-for-ai で追加できることをユーザーに伝えてください。依頼されていない限り、インストールしないでください。

リソースと動詞

リソースとエイリアスは dtctl commands（初期化時に実行）で確認できます。これには、analyzer、anomaly-detector、app、aws/azure/gcp connection & monitoring、bucket、copilot-skill、dashboard、document、edgeconnect、environment、extension、extension-config、function、group、intent、license、license-settings、lookup、notebook、notification、sdk-version、segment、settings、settings-schema、slo、slo-template、trash、user、workflow、workflow-execution が含まれます。名前ではなく ID を使用してください。名前は曖昧な場合があり、失敗することがあります。

動詞	例
get / describe	dtctl get workflows --mine · dtctl describe workflow <id>
apply / edit / delete	dtctl apply -f wf.yaml --set env=prod · dtctl delete workflow <id>
exec	dtctl exec function <id> --payload '{...}' · dtctl exec analyzer <id> --input '{...}'（workflow、copilot も同様）
query / wait	dtctl query "fetch logs | limit 10" · dtctl wait query ... --for=any
inspect	dtctl inspect <file> --head 20 · --tail、--page --offset N --limit M、--fields a,b、--schema、--stats、--sample N、--list（スピルされた結果ファイルの行にアクセスします。Grail への再クエリは不要です）
logs / history / restore	dtctl logs workflow-execution <id> · dtctl history dashboard <id> · dtctl restore dashboard <id> 3（バージョンは位置引数です。スナップショットが存在するのは、更新時に --create-snapshot を渡した場合のみです）
share / unshare	dtctl share dashboard <id> --user [email protected]
find / open	dtctl find intents --data trace.id=abc · dtctl open intent <app/intent> --data k=v
diff / verify	dtctl diff -f wf.yaml · dtctl verify query 'fetch logs' --fail-on-warn · dtctl verify analyzer <id> -f in.json

Davis アナライザー：実行する前に dtctl describe analyzer <id> を実行すると、必須／任意の入力と結果スキーマを確認できます（完全なドキュメントには --doc、未加工のスキーマには -o json を追加します）。dtctl verify analyzer <id> -f in.json は、実行せずに入力を検証します（有効なら終了コード 0／無効なら 1）。

エージェント向けの出力

--agent／-A は AI 環境で自動検出されます（--plain を有効にします。無効にするには --no-agent を指定します）。出力は {ok, result, context} の形式でラップされます（エラーは {ok:false, error:{code,message}} の形式で、context には total、has_more、suggestions が含まれます）。

-o toon          # token-efficient structured output — prefer for agents
-o json|yaml|csv # other machine formats
-o jsonl|parquet # streaming / columnar export for large results (pipe to a file, query with DuckDB)
-o chart|sparkline|barchart   # time series
-o table|wide    # human-readable (table is the default)
--jq '.[].id'    # filter structured output (json|yaml|toon; other formats auto-promote to json)

トークンを節約するには、--agent と -o toon、--jq を併用してください。エージェントモードの query は、デフォルトでメタデータをコスト／サンプリング関連のフィールドに絞り込みます。完全なブロックを表示するには -M=all を指定します。

クエリ結果：result.kind に応じて分岐する

エージェントモードでは、dtctl query はデフォルトで --spill=auto を使用します。大きな結果はローカルファイルにスピルされ、行をコンテキストにすべて出力する代わりに要約が返されます。result が配列だと決めつけず、result.kind に応じて分岐してください。

result.kind	意味 → 対応
records	行は result.records の下にインラインで含まれます → そのまま使用します
result-file	スピルされています。path、format、rows、bytes、列の統計情報、sample_rows を含むマニフェストが返されます → dtctl inspect <path> でファイルを調べます（下記参照）。再クエリしないでください
summary-only	行を書き出せませんでした。path を除いたマニフェストが返されます → 統計情報／サンプルを使用するか、原因に応じた context.suggestions（--spill=never と上限指定、または --spill-to <path>）に従います

未知の kind は不透明なものとして扱い、context（decided、total、warnings、suggestions）にフォールバックしてください。サンプリングされた結果では、統計情報は sample_stats ブロック（basis: "sample"）に格納されます。これは母集団全体の実態ではありません。

dtctl query "fetch logs | limit 1000000" --agent     # auto-spills if large
dtctl query "fetch logs" --spill=never               # force every row inline
dtctl query "fetch logs" --spill-to ./out.jsonl      # explicit path: jsonl|json|csv|parquet
dtctl query "fetch logs" --spill=auto --spill-threshold 100KB

インライン結果にも上限があります。文字列値はデフォルトで 500 文字に切り詰められ、末尾に …(+N chars) が付きます（完全な値を取得するには --max-field-chars 0 を指定します。特定の列だけを取得するには | fields <col> を追加します）。--max-output-tokens N／--max-output-bytes SIZE を指定すると、収まる行だけが返されます。context.truncated が true の場合、結果は不完全です。切り詰められたフィールドは truncated_fields に列挙され、returned < total の場合は行が欠落しています。その場合は、context.next（dtctl inspect コマンド）を実行して、再クエリせずに next_offset から続行してください。

スピルしたファイルを調べる（Grail の再クエリなし）

dtctl inspect <file> は、要約から省かれた行を読み取ります。範囲を限定したストリーミング形式で、エージェントのコンテキストに適しているため、Grail スキャンを再実行する必要はありません。呼び出しごとにプリミティブを必ず 1 つだけ選択してください。

dtctl inspect <path> --head 20                          # first N rows (the manifest never carried rows)
dtctl inspect <path> --tail 10                          # last N rows
dtctl inspect <path> --page --offset 1000 --limit 50    # a window deep in the result (file order)
dtctl inspect <path> --head 20 --fields timestamp,content  # project columns (composable)
dtctl inspect <path> --schema                           # re-derive columns + types + null counts
dtctl inspect <path> --stats                            # re-derive the per-column profile (or --stats=col,col)
dtctl inspect --list                                    # lost the path? enumerate spilled files in this context

これはクエリエンジンではありません。フィルター／SQL／GROUP BY は使えません。集計する場合は、処理を DQL に戻してください（… | summarize …）。複雑なローカル分析には、お好みのローカル分析ツールにファイルを渡してください。大きすぎる inspect ウィンドウはコンテキストをあふれさせる代わりに、新しいファイルへ再度スピルします。また、別のコンテキスト／テナントのファイルは拒否します。

ログパターン分析（トークンを節約）

フリーテキストログのトリアージでは、生の content をダンプせず、まずサーバー側で分類情報を抽出してから掘り下げます。

1. dtctl exec analyzer dt.statistics.clustering.LogPatternExtractor --input '{"logQuery":"<DQL>","numberOfExamples":2}' → DPL テンプレートと一致数。logQuery は timestamp と content を返すプレーンな DQL 文字列です（オブジェクトではありません）。--jq で {patternExpression, numberOfMatches} に射影できます。
2. patternExpression をそのまま parse content, "..." に移し、キャプチャ名を f_1 → 意味のある名前に変更してから、summarize … by:{field} で行単位の抽出／カウントを行います。一致しない行のキャプチャは null になります。
3. 生の行が必要ですか？fetch … --agent で掘り下げてスピルさせ（上記参照）、その後 dtctl inspect <path> --head/--page で読み取ります（上記参照）。

適用とテンプレート

dtctl apply はべき等です。新しい場合は POST、ファイルに id がある場合は PUT を実行します。YAML／DQL ファイルでは、--set で値を設定する Go テンプレートを使用できます。

title: "{{.environment}} Deployment"
cron: "{{.schedule | default "0 0 * * *"}}"

dtctl apply -f file.yaml --set environment=prod --set schedule="0 6 * * *"

ダッシュボード

作成／更新：dtctl apply -f dashboard.yaml。参照用にエクスポート：dtctl get dashboard <id> -o yaml --plain。完全なスキーマと visualizationSettings については、references/resources/dashboards.md を参照してください。

name: "Dashboard Name"
type: dashboard
content:
  settings:
    defaultTimeframe: { enabled: true, value: { from: now()-2h, to: now() } }
  layouts:
    "1": { x: 0, "y": 0, w: 12, h: 6 }    # 24-col grid (full=24); quote "y" (YAML bool)
  tiles:
    "1":
      title: "Tile"
      type: data                          # data | markdown
      query: "fetch logs | limit 10"
      visualization: lineChart            # singleValue|lineChart|areaChart|barChart|pieChart|table|honeycomb|scatterplot
      davis: { enabled: false, davisVisualization: { isAvailable: true } }

注意点：データタイルでは davis.enabled: false を設定してください。ログ／スパンの時系列には makeTimeseries、メトリクスには timeseries を使用します。id がある場合は更新、ない場合は作成します。作成時の version 警告は問題ありません。

権限と安全性

• 変更を加える前に確認してください：dtctl auth can-i <verb> <resource>。スコープについては、TOKEN_SCOPES.md を参照してください。
• 破壊的操作は安全レベルによってブロックされる場合があります。dtctl config use-context <name> で切り替えるか、コンテキストの作成時にレベルを引き上げてください。
• まず get／describe を使ってください。--mine は所有するリソースに対象を限定し、--plain はすべての機械処理に使用します。

認証情報と後片付け

認証情報の管理は dtctl の役割です。読み取りと削除は dtctl を通じてのみ行ってください。

dtctl config delete-context <name> --delete-credentials  # context + its credential
dtctl config delete-credentials <token-ref>              # credential alone (shared, or context already gone)
dtctl auth status --plain                                # presence check — never prints the token

どのような目的であっても、OS のキーチェーンツールを呼び出さないでください。後片付けも例外ではありません。security（macOS）、secret-tool（Linux）、cmdkey（Windows）は使用しないでください。これらの削除コマンドは、認証情報が保存されている場所の大半を見落とします。読み取りコマンドはシークレットを表示し、security dump-keychain は dtctl のものだけでなく、マシン上のすべてのキーチェーンを対象にします。削除を確認するために、シークレットを読み戻さないでください。トークンを表示する後片付け手順は、破棄するよう指示されたものをそのまま漏えいさせています。

詳細

トラブルシューティング · マルチテナント設定 · DQL · ノートブック · 拡張機能 · dtctl --help、dtctl <command> --help