dt-app-notebooks

Dynatrace Notebook スキル

概要

Dynatrace ノートブックは、Document Store に保存される JSON ドキュメントです。物語を記述する markdown ブロックと、ビジュアライゼーションを備えた DQL クエリ用の dql ブロックからなる、順序付けられた セクション の配列を含みます。セクションは配列の順序に従って上から下へ表示されます。

使用する場面： ノートブックの作成、変更、クエリ、分析。

ノートブックの JSON 構造

{
  "name": "My Notebook",
  "type": "notebook",
  "content": {
    "version": "7",
    "defaultTimeframe": { "from": "now()-2h", "to": "now()" },
    "sections": [
      { "id": "1", "type": "markdown", "markdown": "# Title" },
      {
        "id": "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
          }
        }
      }
    ]
  }
}

• セクションは配列の順序に従って表示されます。
• セクションの種類：markdown、dql。（function もありますが、まれです。）
• 文字列の ID（"1"、"2"、…）を使用します。UUID も受け付けられます。
• content.defaultTimeframe はデフォルトの時間枠を設定します。各セクションでは section.state.input.timeframe を使って上書きできます。DQL でハードコードされた時間フィルターを使用することもできます。

任意の content プロパティ： defaultSegments。

読み取りと分析

dtctl get notebook <id> -o json を使って完全なコンテンツを取得します（describe が返すのはメタデータのみです）。次に、JSON を調べて利用可能なプロパティを確認します。分析の前に、references/analyzing.md をよく読んでください。

作成・更新ワークフロー（必須の順序）

references/create-update.md に記載されているワークフローに必ず従ってください。

重要なルール：

• クエリを生成する前に、ドメインスキルを読み込みます。DQL を作り出してはいけません。
• ノートブックに追加する前に、すべてのセクションクエリを検証します。
• デプロイする前に name を設定します。
• ユーザーが特定のビジュアライゼーションタイプを指定していない限り、visualizationSettings では autoSelectVisualization: true を優先します。false の場合は、state.visualization を明示的に設定する必要があります。
• 更新時は、必ず最初に現在の状態を読み取ります： dtctl get notebook <id> -o json を実行し、notebook.json として保存してから、そのファイルを変更し、デプロイします。JSON を一から再構築したり、id を手動で挿入したりしないでください。どちらも、前回のデプロイ以降にユーザーが UI で行った編集を、通知なく上書きしてしまいます。
• dtctl apply でデプロイします。検証は自動的に実行されます。失敗した場合は、再適用する前に報告されたエラーをすべて修正します。

ビジュアライゼーションの種類

ノートブックでは、Dynatrace のビジュアライゼーションの一部をサポートしています。

• 時系列（timeseries／makeTimeseries が必要）：lineChart、areaChart、barChart、bandChart
• カテゴリ別（summarize ... by:{field}）：categoricalBarChart、pieChart、donutChart
• 単一値／ゲージ／メーター：singleValue、meterBar、gauge
• 表形式（任意のデータ形状）：table、raw、recordView
• 分布／ステータス：histogram、honeycomb
• 地図：choropleth、dotMap、connectionMap、bubbleMap
• マトリックス／相関：heatmap、scatterplot

各ビジュアライゼーションで必要なフィールドの種類：references/sections.md。

参考資料

ファイル	読み込むタイミング
create-update.md	ノートブックの作成／更新
sections.md	セクションの種類、ビジュアライゼーションのフィールド要件、設定
analyzing.md	ノートブックの読み取り、クエリの抽出、目的の特定