Dynatrace Notebook Skill

このスキルの使用方法

NotebookとDashboardは構造的に似ています。すべてのワークフロー（作成、変更、クエリ、分析）について dt-app-dashboards スキルに従い、以下で説明する相違点を適用してください。

必須の作成/更新ワークフロー

1. クエリを生成する前にドメインスキルをロードする — DQLを発明しないこと
2. notebookに追加する前に、dtctl query '<DQL>' --plain ですべてのクエリを検証する
3. visualizationSettings に "autoSelectVisualization": true を常に設定 してください。ユーザーが明示的に特定の可視化タイプをリクエストしない限り
4. deploy_notebook.sh 経由でデプロイする必ず — dtctl apply を直接使用しないこと:

   bash scripts/deploy_notebook.sh notebook.json
   

   スクリプトはまずnotebookを検証し、エラーがあるとデプロイをブロックします。スキップすると破損したnotebookをデプロイするリスクがあります。 デプロイに成功すると、ローカルファイルは削除されます。
5. 既存のnotebookを更新する場合：最初にダウンロード して dtctl get notebook <id> -o json --plain > notebook.json、変更してからデプロイします。ゼロから再構築したり、手動で id を注入しないこと。

Notebook JSON構造

{
  "name": "My Notebook",
  "type": "notebook",
  "content": {
    "version": "7",
    "defaultTimeframe": { "from": "now()-2h", "to": "now()" },
    "sections": [
      { "id": "uuid-1", "type": "markdown", "markdown": "# Title\nContext" },
      {
        "id": "uuid-2", "type": "dql", "title": "Query Section", "showInput": true,
        "state": {
          "input": { "value": "fetch logs | summarize count()" },
          "visualization": "table",
          "visualizationSettings": { "autoSelectVisualization": true, "chartSettings": {} },
          "querySettings": {
            "maxResultRecords": 1000, "defaultScanLimitGbytes": 500,
            "maxResultMegaBytes": 1, "defaultSamplingRatio": 10, "enableSampling": false
          }
        }
      }
    ]
  }
}

Dashboardとの主な相違点

ドキュメント構造

項目	Dashboard	Notebook
type	"dashboard"	"notebook"
content.version	21 (数値)	"7" (文字列)
コンテンツブロック	tiles (オブジェクトマップ) + layouts (オブジェクトマップ)	sections (順序付き配列)
変数	content.variables[] with query, csv, text types	なし
レイアウト/グリッド	layouts 経由の24ユニットグリッド (x, y, w, h)	なし — セクションは配列順に上から下へレンダリング
デフォルトタイムフレーム	UIのタイムピッカーで制御	content.defaultTimeframe オブジェクト (from/to 付き)

セクションタイプ vs タイルタイプ

Dashboardには2つのタイルタイプ (markdown, data) があります。Notebookには3つのセクションタイプがあります：

• markdown — 同じコンセプト。フィールド：id, type, markdown
• dql — Dashboard の data タイルと同等ですが、クエリと可視化は state 内にネストされています（下の表を参照）

クエリと可視化のパスマッピング

フィールド	Dashboard タイル	Notebook DQL セクション
クエリ文字列	tile.query	section.state.input.value
可視化タイプ	tile.visualization	section.state.visualization
可視化設定	tile.visualizationSettings	section.state.visualizationSettings
クエリ設定	tile.querySettings	section.state.querySettings
セクション固有のタイムフレーム	N/A (UIピッカーがすべてのタイルを制御)	section.state.input.timeframe

Notebook専用のセクションプロパティ

• autoSelectVisualization (boolean, visualizationSettings 内) — true の場合、Dynatrace はクエリ結果に対して最適な可視化タイプを自動的に選択します。ユーザーが特定の可視化設定を好まない場合は true を推奨します。false に設定すると、state.visualization を希望のタイプに明示的に設定する必要があります。
• showTitle (boolean) — セクションタイトルの表示/非表示
• showInput (boolean, デフォルト true) — クエリエディタの表示/非表示。明示的にリクエストされない限り、常に true に設定してください。
• height (数値, px) — セクションの高さ (デフォルト ~400)
• drilldownPath — ドリルダウンインタラクションのナビゲーションパス
• filterSegments — セクションレベルのフィルターセグメント
• davis — Davis AI Copilot設定

利用可能な可視化

Notebookは以下をサポート：table, lineChart, areaChart, barChart, categoricalBarChart, pieChart, donutChart, singleValue, bandChart, histogram, honeycomb, raw, recordView

Dashboard スキルから適用されないもの

• 変数 — Notebookには変数がありません。すべての変数セクションを無視してください：タイプ、置換パターン ($Var, array($Var))、依存関係解決、変数検証。
• レイアウト/グリッド — ポジショニングシステムはありません。配列内のセクション順序 = 表示順序。x, y, w, h はありません。
• タイルID / レイアウトIDのマッチング — 適用不可 (layouts オブジェクトがありません)。
• UIタイムフレームピッカーの警告 — Notebookにはダッシュボード形式のすべてのクエリを制御するタイムピッカーがありません。代わりに content.defaultTimeframe がデフォルトを設定し、各セクションは section.state.input.timeframe で上書きできます。Notebookではクエリのハードコードされたタイムフィルターは許可されます。
• クエリ内の変数置換 — 適用不可。

検証とデプロイ

scripts/ ディレクトリのスクリプトを使用してください：

• notebook-validator.js — Notebookの構造を検証し、すべてのDQLクエリを実行します。以下経由で実行：

  cat notebook.json | jq '{notebook: .}' | dtctl exec function -f scripts/notebook-validator.js --data - --plain | jq -r .result
  

  または notebook ID で：echo '{"notebookId":"<id>"}' | dtctl exec function -f scripts/notebook-validator.js --data - --plain | jq -r .result

• deploy_notebook.sh — 検証してからデプロイ：

  bash scripts/deploy_notebook.sh notebook.json
  bash scripts/deploy_notebook.sh --dry-run notebook.json
  

関連スキル

• dt-app-dashboards — すべてのワークフローの基本スキル。このスキルは相違点のみドキュメント化
• dt-dql-essentials — DQLクエリ構文、関数、最適化