Dynatrace Control with dtctl

dtctl (kubectl のようなスタイルの Dynatrace 用 CLI) を操作します。このスキルは dtctl のコマンドパターンと基本的な操作を教えます。

推奨される初期化

タスク開始時に、これらのチェックを実行してコンテキストと権限を確認します:

# 利用可能なコマンド、フラグ、リソースをすべて検出
dtctl commands --brief -o json

# 現在のコンテキストを表示
dtctl config current-context

# コンテキストの詳細を表示
dtctl config describe-context $(dtctl config current-context) --plain

# 認証済みユーザーを表示
dtctl auth whoami --plain

これにより以下が表示されます:

• 現在のコンテキスト名と環境 URL
• セーフティレベル (readonly, readwrite-mine, readwrite-all, dangerously-unrestricted)
• 認証済みユーザー ID (名前、メール、UUID)

DQL リファレンス使用法

Dynatrace データを取得する DQL (例えば dtctl query、dtctl wait query、またはクエリファイル経由) を書き、修正、または実行する前に、必ず references/DQL-reference.md を参照して、ドキュメント化されている構文とテンプレートに従う必要があります。

メモリ/仮定とリファレンスに矛盾がある場合は、リファレンスを優先してください。

前提条件

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

リソースとコマンド

利用可能なリソース

dtctl はすべてのリソースタイプに統一されたパターンを使用します。dtctl describe <resource> <id> -o json --plain で実際の出力からスキーマを検出します。

リソース	エイリアス
analyzer	analyzers
app	apps
bucket	bkt
copilot-skill	copilot-skills
dashboard	dash
edgeconnect	ec
extension	ext, extensions
extension-config	extcfg, extension-configs
function	fn, func
group	groups
intent	intents
lookup	lookups, lkup
notebook	nb
notification	notifications
sdk-version	sdk-versions
settings	setting
settings-schema	schema
slo	-
slo-template	slo-templates
trash	deleted
user	users
workflow	wf
workflow-execution	wfe

曖昧さを回避するため、名前ではなく ID を使用してください。

コマンド動詞

動詞	説明	例
get	リソースを一覧表示	dtctl get workflows --mine
describe	リソース詳細を表示	dtctl describe workflow <id>
edit	リソースを対話的に編集	dtctl edit dashboard <id>
apply	ファイルから作成/更新	dtctl apply -f workflow.yaml --set env=prod
delete	リソースを削除	dtctl delete workflow <id>
exec	ワークフロー/関数/アナライザー/Copilot を実行	dtctl exec workflow <id>
query	DQL クエリを実行	dtctl query "fetch logs | limit 10"
logs	リソースログを出力	dtctl logs workflow-execution <id>
wait	条件を待機	dtctl wait query "fetch logs" --for=any
history	ドキュメント履歴を表示	dtctl history dashboard <id>
restore	ドキュメントバージョンを復元	dtctl restore dashboard <id> --version 3
share	ドキュメントを共有	dtctl share dashboard <id> --user email@example.com
unshare	共有を削除	dtctl unshare dashboard <id> --user email@example.com
find	リソースを検出	dtctl find intents --data trace.id=abc
open	ブラウザで開く	dtctl open intent <app/intent> --data key=value
diff	リソースを比較	dtctl diff -f workflow.yaml
verify	実行せずに検証	dtctl verify query 'fetch logs' --fail-on-warn
commands	すべてのコマンドを一覧表示 (機械可読形式)	dtctl commands --brief -o json

AI エージェント向けの主要な概念

出力モード

# エージェントエンベロープモード (AI 環境で自動検出)
-A, --agent      # ok/result/error/context を含む構造化 JSON エンベロープ
--no-agent       # 自動検出されたエージェントモードをオプトアウト

# マシン可読形式 (AI エージェント向け)
-o json          # JSON 出力
-o yaml          # YAML 出力
-o csv           # CSV 出力
-o chart         # ASCII チャート (時系列)
-o sparkline     # ASCII スパークライン (時系列)
-o barchart      # ASCII 棒グラフ (時系列)

# 人間可読形式
-o table         # テーブル形式 (デフォルト)
-o wide          # より多くの列を含むワイドテーブル

# AI 消費向けに常に --plain フラグを使用 (--agent に含まれる)
--plain          # 色とプロンプトを削除、解析に最適

AI エージェント向けに推奨: dtctl <command> --agent (自動検出) または dtctl <command> -o json --plain

--agent エンベロープは結果と共に構造化メタデータを提供します:

{
  "ok": true,
  "result": [ ... ],
  "context": {
    "verb": "get", "resource": "workflow",
    "total": 5, "has_more": false,
    "suggestions": ["Run 'dtctl describe workflow <id>' for details"]
  }
}

テンプレート変数

YAML/DQL ファイルでは、Go テンプレート構文を使用します:

# workflow.yaml
title: "{{.environment}} Deployment"
owner: "{{.team}}"
trigger:
  schedule:
    cron: "{{.schedule | default "0 0 * * *"}}"

# query.dql
fetch logs
| filter host.name == "{{.host}}"
| filter timestamp > now() - {{.timerange | default "1h"}}

実行: dtctl apply -f file.yaml --set environment=prod --set team=platform

Copilot、関数、アナライザー

# Copilot スキル
dtctl get copilot-skills -o json --plain

# 関数
dtctl get functions -o json --plain
dtctl exec function <id-or-name> --payload '{"key":"value"}' --plain

# アナライザー
dtctl get analyzers -o json --plain
dtctl exec analyzer <id-or-name> --input '{"timeframe":"now-2h"}' --plain

最初に get ... -o json --plain を優先し、その後明示的な ID で describe/exec を実行します。

認証と権限

# 現在のユーザーと権限を確認
dtctl auth whoami --plain
dtctl auth can-i create workflows
dtctl auth can-i delete dashboards

操作を実行する前に can-i を使用して権限を確認してください。

クイックリファレンス: DQL クエリ

DQL データ取得の必須ワークフロー:

1. まず references/DQL-reference.md を参照
2. ドキュメント化されているパターンを使用してクエリをビルド/検証
3. dtctl query ... -o json --plain で実行 (結果を待つ場合は dtctl wait query ...)

# インラインクエリ
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

# クエリ結果を待機
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

ダッシュボード

完全な例とフィールドレベルの注意事項については、references/resources/dashboards.md を参照してください。

作成/更新: dtctl apply -f dashboard.yaml --plain。参照用にエクスポート: dtctl get dashboard <id> -o yaml --plain。

YAML スケルトン

name: "Dashboard Name"
type: dashboard
content:
  annotations: []
  importedWithCode: false
  settings:
    defaultTimeframe:
      enabled: true
      value: { from: now()-2h, to: now() }
  layouts:
    "1":                    # 文字列キー、タイルキーと一致する必要あり
      x: 0                 # 24 列グリッド (全幅=24, 半幅=12, 1/3 幅=8)
      "y": 0               # YAML ブール値解析を避けるため "y" をクォート必須
      w: 12
      h: 6
  tiles:
    "1":
      title: "Tile Title"
      type: data            # data | markdown
      query: |
        fetch logs | limit 10
      visualization: lineChart
      visualizationSettings:
        autoSelectVisualization: false
      davis: { enabled: false, davisVisualization: { isAvailable: true } }

タイルタイプとビジュアライゼーション

• type: data — query + visualization を持つ DQL タイル: singleValue、lineChart、areaChart、barChart、pieChart、table、honeycomb、scatterplot
• type: markdown — content フィールド経由の静的テキスト (markdown をサポート)

詳細な visualizationSettings (singleValue、チャート、テーブル、閾値、単位オーバーライド) については、references/resources/dashboards.md を参照してください。

注意事項

• データタイルの davis.enabled: false を常に設定してください。
• ログ/スパンの時系列には makeTimeseries を、メトリクスには timeseries を使用します。
• 作成時の version フィールド警告は無害です。
• id フィールドなし → 新規作成; id フィールドあり → 既存を更新

よくある問題

名前解決の曖昧性:

• 名前が複数のリソースにマッチする場合、dtctl は失敗します
• 解決策: 名前の代わりに ID を使用
• ID を検出: dtctl get <resource> -o json --plain | jq -r '.[] | "\(.id) | \(.name)"'

権限拒否:

• トークンスコープを確認: https://github.com/dynatrace-oss/dtctl/blob/main/docs/TOKEN_SCOPES.md
• 権限を検証: dtctl auth can-i <verb> <resource>
• セーフティレベルを確認: dtctl config describe-context $(dtctl config current-context) --plain

コンテキスト/セーフティ制限:

• 破壊的な操作はセーフティレベルによってブロックされる可能性があります
• コンテキストを切り替え: dtctl config use-context <name>
• コンテキスト作成時にセーフティレベルを調整

追加リソース

• トラブルシューティング: references/troubleshooting.md
• マルチテナント設定: references/config-management.md
• DQL 構文とテンプレート: references/DQL-reference.md
• ノートブック: references/resources/notebooks.md
• 拡張機能: references/resources/extensions.md
• CLI ヘルプ: dtctl --help、dtctl <command> --help

セーフティリマインダー

• マシン/AI 消費向けに --plain を使用
• 破壊的な操作の前にコンテキストとセーフティレベルを確認し、最初に get/describe を優先
• 所有しているリソースをフィルタリングするために --mine フラグを使用
• マルチテナント作業の場合は references/config-management.md を参照