building-dashboards

ダッシュボードの構築

基本方針

1. 意思決定を最優先します。 すべてのパネルが、アクションにつながる問いに答えます。
2. 概要 → 詳細表示 → 根拠。 広い視点から始め、クリックやフィルターで絞り込み、最後に生ログを確認します。
3. 平均よりも割合とパーセンタイルを重視します。 平均値では問題が隠れてしまいますが、p95／p99 なら問題が明らかになります。
4. 情報を詰め込むより、シンプルにします。 パネルごとに問いは1つです。余計なグラフ要素は使いません。
5. データで検証します。 フィールドを推測せず、まずスキーマを確認します。
6. 求められた値を計算するか、後回しにします。 パネルを計算できない場合は、障害要因を記載した Note に置き換えます。たとえ明記したとしても、別の値で代用してはいけません。計算するか、後回しにするを参照してください。

---

エントリーポイント

開始地点	ワークフロー
曖昧な説明	要件の聞き取り → データセットの種類を確認 → ブループリントを設計（APL または MPL） → パネルごとにクエリを作成 → デプロイ
テンプレート	テンプレートを選択 → データセット／サービス／環境をカスタマイズ → デプロイ
Splunk ダッシュボード	SPL を抽出 → spl-to-apl で変換 → グラフの種類を割り当て → デプロイ
Grafana ダッシュボード	標準的なパネル仕様（expr、legendFormat、unit、title、description）を割り当て → PromQL を変換 → グラフの種類を割り当て → デプロイ。reference/grafana-migration.mdを参照してください。
探索	axiom-sre を使ってスキーマ／シグナルを確認 → パネルとして実用化

---

要件の聞き取り：最初に確認すること

1. 対象者と意思決定

   • オンコールのトリアージですか？（高速更新、エラー重視）
   • チームの健全性確認ですか？（日次トレンド、SLO 追跡）
   • 経営報告ですか？（週次サマリー、概要レベル）

2. 対象範囲

   • サービス、環境、リージョン、クラスター、エンドポイントのどれですか？
   • 単一サービスの表示ですか、それとも複数サービスを横断した表示ですか？

3. データセットの種類。 MCP の listDatasets を使い、kind を確認します。別途設定されたデプロイメントでは、scripts/metrics/datasets <deploy> を使います。

   • otel:metrics:v1 ／ otel-metrics-v1 → メトリクスデータセットです。メトリクスの手順に従います。
   • それ以外 → イベント／ログデータセットです。APL の手順に従います。

   メトリクスデータセットに getschema を実行してはいけません。 エラーは発生しませんが、0 行が返されます。

   APL の手順： ['dataset'] | where _time between (ago(1h) .. now()) | getschema でフィールドを確認します。手順4～5に進みます。

   メトリクスの手順： メトリクスの確認とクエリには Axiom MCP を使い、その後メトリクス／MPL ブループリントに従います。

4. ゴールデンシグナル（APL の手順）

   • トラフィック：リクエスト数／秒、イベント数／分
   • エラー：エラー率、5xx 件数
   • レイテンシ：p50、p95、p99 の処理時間
   • 飽和度：CPU、メモリ、キューの深さ、接続数

5. 詳細表示のディメンション（APL の手順）

   • ユーザーは何でフィルター／グループ化しますか？（サービス、ルート、ステータス、Pod、customer_id）

---

ダッシュボードのブループリント

データセットの種類に合ったブループリントを選びます。

APL ブループリント（イベント／ログデータセット）

1. ひと目でわかる情報（Statistic パネル）

「今、問題が起きていますか？」に答える単一の数値です。

• エラー率（直近5分）
• p95 レイテンシ（直近5分）
• リクエスト率（直近5分）
• アクティブなアラート（該当する場合）

2. トレンド（TimeSeries パネル）

「何が変わりましたか？」に答える時系列パターンです。

• 時間経過に伴うトラフィック
• 時間経過に伴うエラー率
• 時間経過に伴うレイテンシのパーセンタイル
• 比較のため、ステータス／サービス別に積み上げ表示

3. 内訳（Table／Pie パネル）

「どこを調べるべきですか？」に答える上位項目の分析です。

• 失敗が多いルートの上位10件
• エラーメッセージの上位10件
• エラー率が最も高い Pod
• ステータス別のリクエスト分布

4. 根拠（LogStream + SmartFilter）

「具体的に何が起きましたか？」に答える生イベントです。

• エラーに絞り込んだ LogStream
• サービス／環境／ルートで絞り込む SmartFilter
• 読みやすさのために主要フィールドを表示

メトリクス/MPL ブループリント（メトリクスデータセット）

バケット化には align to $__interval using … を使用します。$__interval はダッシュボードのランタイムから提供されます。固定の時間範囲を使うと、解像度が高すぎたり低すぎたりします。探索と検証には、Metrics/MPL チャートの仕様に従ってください。chart-add --mpl はインラインの時間範囲（[1h..]）を拒否します。

例外：$__interval によってバケットが空になるスパースなメトリクスでは、固定の長い時間範囲（例：1h）を使用できます。その理由をチャートに記載してください。

1. 一目でわかる状態（Statistic パネル）

現在値 — 「今の状態は？」

• パネルに系列全体で何を表示するかに応じて、group 関数を選びます。
• メトリクスのメタデータから unit を読み取り、chart-add --unit に渡します。比率メトリクス（0～1）では、--unit "%" の前に MPL で | map * 100 を適用する必要があります。

2. 推移（TimeSeries パネル）

時間の経過に伴う推移 — 「何が変わったか？」

• 各区間に何を表示するかに応じて、align 関数を選びます。
• カーディナリティの低いタグのみでグループ化します（チャートあたり系列数は 10 以下）。
• 単位を --name に含めます（"P95 Latency (ms)"、"Memory (MiB)"）。MPL で値のスケールを変換します（バイトから MiB への変換には | map / 1048576）。

3. 内訳（TimeSeries または Table パネル）

エンティティごとの詳細 — 「どこを確認すればよいか？」

• エンティティ（ホスト、ポッド、サービス）ごとに分割されたメトリクスです。
• 系列数を管理しやすくするためにフィルターします。
• パネルごとにディメンションを 1 つにします。1 つのチャートに詰め込みすぎないでください。

4. エンティティの状態（TimeSeries または Table パネル）

ブール値／状態メトリクス — 「オン／オフ／アクティブのどれか？」に答えます。

• 各区間で答える状態に関する問いに応じて、align 関数を選びます。
• スパースな状態メトリクスでは、固定の長い時間範囲（1h 以上）が必要になる場合があります。

---

必須のチャート構造

各チャートには一意のケバブケースの id（error-rate、p95-latency）が必要で、すべてのレイアウトの i はいずれかの id と一致する必要があります。同じ id を chart-add --id と layout-pack <id>:… に渡します。dashboard-assemble は出力前に相互チェックします。

---

チャートの単位設定

chart-add --unit にわかりやすい単位文字列（"%"、"s"、"ms"、"B"、"req/s"）を渡します。スクリプトは、チャートタイプごとに unit 列挙値と customUnits の接尾辞を選択します。customUnits はラベルであり、フォーマッターではありません。MPL で値のスケールを変換してください（バイトから MiB への変換には | map / 1048576、バイトから MB への変換には | map / 1000000、0～1 の比率をパーセントにするには | map * 100）。メトリクスチャートでは、メトリクスのメタデータから元の単位を読み取り、そのまま渡します。内部設定（エージェントが jq でマージできる高度なオプション）：reference/chart-config.md。

---

計算するか、後回しにするか

各パネルでは、要求された値を計算するか、妨げとなる要因を記載した Note に置き換える必要があります。別の値で代用することは決して許容されません。免責事項は、その数値をもとに行動する人には伝わらないためです。

後回しにする場合のテンプレート（chart-add --type Note を使用）：

**Deferred — blocked by:** <one-line reason>.

**Original spec:** <what the panel should compute, dimensions, unit>.

**To unblock:** <pointer to the fix>.

よくある妨げとなる要因：MPL パーサーの制限、逆タグに相当するものがなくタグが不足していること、OTel の名前変更に一致するものがなくメトリクスが不足していること。詳細な理由：reference/design-playbook.md § Substituting a Different Quantity。

---

チャートの種類

種類	使用場面	主な制約
Statistic	単一の KPI、現在値	クエリは 1 行を返す必要があります。
TimeSeries	時系列の傾向、パーセンタイルの重ね合わせ	bin_auto(_time) を使用します。複数のパーセンタイルには percentiles_array() を使用します。
Table	上位 N 件のリスト、内訳	top N で上限を設定します。列は project で制御します。
Pie	6 カテゴリ以下の構成比	集計を 6 スライス以下にします。カーディナリティの高いデータには使用しないでください。
LogStream	未加工イベントの確認	take 100–500 を指定し、関連するフィールドに project-keep を適用して、厳密にフィルターします。
Heatmap	分布／レイテンシ密度	summarize histogram(field, buckets) by bin_auto(_time) を使用します。
Scatter Plot	グループごとに 2 つのメトリクスを相関させる	summarize avg(x), avg(y) by group を使用します。
SmartFilter	インタラクティブなフィルターバー	各パネルのクエリで declare query_parameters が必要です。reference/smartfilter.md を参照してください。
Monitor List	モニターのステータス表示	APL は使用しません。UI でモニターを選択してください。
Note	Markdown のコンテキスト、見出し、ランブックへのリンク	chart-add --type Note --text "<md>" を使用します。

種類ごとの APL レシピ：reference/chart-cookbook.md。

---

チャートの設定

chart-add は一般的な設定（種類、ID、名前、クエリ、データセット、単位、スパークライン）に対応しています。サポート対象外のオプション（TimeSeries の aggChartOpts バリエーション、Table／LogStream の tableSettings.columns、hideHeader など）を設定するには、まず chart-add の出力を取得し、jq で追加フィールドをマージします。すべてのオプションについては reference/chart-config.md を参照してください。また、独自のフィールドをマージする前に、拒否対象フィールドの一覧を確認してください。

---

APL のパターン

時間フィルタリング

ダッシュボードのチャートクエリでは、ピッカーから時間範囲が引き継がれるため、_time フィルターは省略します。アドホッククエリ（Axiom の Query タブ、axiom-sre）では、where _time between (ago(1h) .. now()) を明示的に指定する必要があります。

ビンサイズの選択

bin_auto(_time) を使用します。ダッシュボードの時間範囲に合わせて自動調整されます。手動の bin(_time, …) が正当化されるのは、標準外のケース（例：上流のバッチ間隔に合わせる場合）に限られます。その理由を記録してください。

カーディナリティのガードレール

summarize … by … には、top N またはフィルターで上限を設定します。カーディナリティの高いフィールド（user_id、trace_id）で上限なくグループ化すると、処理が膨大になります。

| summarize count() by route | top 10 by count_   // bounded
| summarize count() by user_id                    // unbounded — avoid

フィールドのエスケープ

ドットを含むフィールドには、角括弧表記が必要です。

| where ['kubernetes.pod.name'] == "frontend"

名前にドットを含むフィールド（階層ではない場合）には、エスケープが必要です。

| where ['kubernetes.labels.app\\.kubernetes\\.io/name'] == "frontend"

レシピ

トラフィック、エラー率、レイテンシのパーセンタイルなど、ゴールデンシグナルの APL レシピ：reference/chart-cookbook.md。

---

レイアウトの構成

layout-pack は、種類ごとのデフォルトサイズ（Statistic 3×3、TimeSeries 6×4、Table 6×5、LogStream 12×6、Note 12×2）を使い、チャートを 12 列のグリッドに行優先で配置します。必要に応じて id:WxH で上書きします。グリッドのレシピ：reference/layout-recipes.md。命名規則とパネルの順序付けに関する規約：reference/design-playbook.md。

セクション

折りたたみ可能なグループは、トップレベルの sections 配列です。これを dashboard-assemble に渡してください。チャートファイルに sectionId を作り込んだり、無効な更新を送信して形式を調べたりしないでください。

dashboard-assemble \
  --name "API" \
  --datasets logs \
  --layout /tmp/d/layout.json \
  --section "Requests:err-rate,traffic-ts" \
  --section-collapsed "Errors:top-errors" \
  /tmp/d/c-err-rate.json /tmp/d/c-traffic-ts.json /tmp/d/c-top-errors.json

• タイトルは最初の : より前のテキストです。チャート ID はその後にカンマ区切りで続き、チャートの id と一致している必要があります。
• フラグの順序が表示順です。--section-collapsed は defaultCollapsed: true を設定します。
• セクションの id はタイトルから導出される UUID なので、次回の実行でも同じタイトルなら同じ ID が維持されます。
• どの --section にも含まれないチャートはグループ化されません。すべての SmartFilter チャートはグループ化しないでください。
• グリッドヘッダーとして使う Note はレイアウトであり、セクションではありません。ダッシュボードでグループを折りたたみ、そのクエリを停止する場合は --section を使ってください。

---

ダッシュボードの設定

更新間隔

dashboard-assemble --refresh oncall|team|exec（60/300/900s）を使うか、明示的な整数（≥60）を渡してください。更新間隔を短くし、時間範囲を長くするとクエリのコストが高くなります。exec／週次ボードでは、より長い間隔を選んでください。

共有

API トークンで作成できるのは共有ダッシュボードのみです（owner: "X-AXIOM-EVERYONE"）。プライベートダッシュボードはサポートされていません。ユーザーごとのデータの可視性は、引き続きデータセットの権限によって適用されます。

URL の時間範囲パラメーター

?t_qr=24h（クイック範囲）、?t_ts=...&t_te=...（カスタム）、?t_against=-1d（比較）

---

セットアップ

ツール、前提条件、~/.axiom.toml の設定については、README.md を参照してください。scripts/setup で確認してください。

---

デプロイ

スクリプト

スクリプト	用途
scripts/chart-add --type <T> --id <id> --name <n> [--apl <q> | --mpl <q> --dataset <d>] [--unit <u>]	単一のチャート JSON を標準出力に出力します。APL と MPL を使い分けます。MPL クエリにインラインの時間範囲がないかを確認し、チャートの種類ごとに単位フィールドを適用します。
scripts/layout-pack <id>:<Type|WxH> ...	レイアウト JSON 配列を標準出力に出力します。12 列のグリッドに行優先で配置し、種類名をデフォルトのサイズに対応付けます。
scripts/dashboard-assemble --name … --datasets … --layout F.json [--section TITLE:id,id ...] [opts] CHART_FILES…	チャートファイルとレイアウトから完全なダッシュボード JSON を構成します。外枠（owner、schemaVersion、qr- プレフィックス、refreshTime の検証、ID の相互チェック、sections）を管理します。
scripts/dashboard-list <deploy>	すべてのダッシュボードを一覧表示します
scripts/dashboard-get <deploy> <id>	ダッシュボード JSON を取得します
scripts/dashboard-validate <file>	JSON 構造を検証します
scripts/dashboard-create <deploy> <file>	ダッシュボードを作成します
scripts/dashboard-update <deploy> <id> <file>	更新します（バージョンが必要です）
scripts/dashboard-chart-patch <deploy> <id> <chart-id> <patch-file> (--version <version> | --overwrite)	1 つのチャートにパッチを適用します
scripts/dashboard-copy <deploy> <id>	ダッシュボードを複製します
scripts/dashboard-link <deploy> <id>	共有可能な URL を取得します
scripts/dashboard-delete <deploy> <id>	ダッシュボードを削除します（確認あり）
scripts/axiom-api <deploy> <method> <path>	ダッシュボード／アプリ API 専用（app.* に書き換えます）。データ／メトリクスのエンドポイントには scripts/metrics/axiom-api を使用してください
scripts/metrics/axiom-api <deploy> <method> <path>	データ／メトリクス API（エッジルーティング用の AXIOM_URL_OVERRIDE をサポートします）
scripts/metrics/datasets <deploy>	kind とエッジデプロイメントを含むデータセットを一覧表示します
scripts/metrics/metrics-spec	MPL クエリ仕様を取得します
scripts/metrics/metrics-info <deploy> <dataset> ...	メトリクス、タグ、値を確認します
scripts/metrics/metrics-query <deploy> <mpl> <start> <end>	メトリクスクエリを実行します（生のクエリ — $__interval は注入されません）
scripts/metrics/mpl-validate-chart <deploy> '<MPL>' [start] [end] [--interval D]	チャートの MPL パイプラインを検証します。param $__interval: Duration; と -p __interval=… を自動的に注入し、インラインの時間範囲を拒否します。チャートクエリを作成する際は、生の metrics-query の代わりにこれを使用してください。

2 つの axiom-api スクリプトは互換性がありません。scripts/axiom-api はダッシュボードアプリ API 用、scripts/metrics/axiom-api はデータ／メトリクスのエンドポイントとエッジルーティング用です。間違った方を使うと 404 になります。

対象を指定したチャートの更新

既存のチャートを 1 つ変更し、ダッシュボードのレイアウト、メタデータ、その他のチャートには手を加えない場合は、scripts/dashboard-chart-patch を使用します。このスクリプトは、リクエストの chart フィールドに JSON Merge Patch を指定して、PATCH /v2/dashboards/uid/{uid}/charts/{chartId} を呼び出します。

パッチファイルには、変更するチャートフィールドだけを記述します。

{
  "name": "Error Rate (5m)",
  "query": { "apl": "['logs'] | summarize errors=countif(status >= 500)" },
  "config": { "stale": null }
}

null は既存のフィールドを削除します。ネストされたオブジェクトは再帰的にマージされます。パッチに id が含まれている場合、<chart-id> のパス引数と一致する必要があります。保存前に、サーバーは変更後のダッシュボード全体を検証します。

ダッシュボードを dashboard-get で取得した後、楽観的同時実行制御を行うには --version <version> を使用します。--overwrite は、最終書き込み優先の動作を意図する場合にのみ使用してください。レイアウトの変更、複数チャートの編集、ダッシュボードのメタデータ、オーナー、更新間隔、時間範囲を変更する場合は、引き続き dashboard-update を使用してください。

ワークフロー

chart-add、layout-pack、dashboard-assemble が JSON の構造を管理します。各チャートはそれぞれ専用の一時ファイルに保存し、チャートのようなデータがエージェントのコンテキストに戻ることはありません。

1. スキーマを検出します（イベントには axiom-sre / getschema、メトリクスには Axiom MCP を使用します）。
2. 各パネルのクエリを作成します。明示的な時間フィルターを付けて axiom-sre で APL を検証し、MPL については Metrics/MPL chart contract に従います。
3. チャートごとに chart-add --type … --apl '<APL>' または chart-add --type … --mpl '<MPL>' --dataset <name> を実行し、それぞれ専用のファイルにリダイレクトします。
4. レイアウトには layout-pack <id>:<Type|WxH> … を使用します（ID は表示順に指定します）。
5. dashboard-assemble --name … --datasets … --layout LAYOUT [--section TITLE:id,id ...] CHART_FILES… で組み立てます。折りたたみ可能なグループごとに --section を繰り返します。グループを折りたたんだ状態で開始する場合は --section-collapsed を使用します。
6. dashboard-validate を実行してから、dashboard-create（または dashboard-update）を実行します。
7. URL には dashboard-link を使用します。URL を手作業で組み立ててはいけません。

---

関連スキルの統合

• spl-to-apl — Splunk SPL → APL（timechart → TimeSeries、stats → Statistic/Table）。reference/splunk-migration.md を参照してください。
• axiom-sre — getschema によるスキーマ検出、ベースラインの調査。

---

テンプレート

chart-add + layout-pack + dashboard-assemble で組み立てます。事前構築済みテンプレートはレガシー用途のため、引き続き reference/templates/（blank.json、service-overview.json、service-overview-with-filters.json、api-health.json）にあります。dashboard-from-template でテンプレートをインスタンス化できますが、特定のフィールド名（service、status、route、duration_ms）を前提としており、sed による修正が必要です。新規作業では、組み立て方式を優先してください。

---

よくある落とし穴

問題	原因	解決方法
getschema が 0 行を返す	Dataset が otel:metrics:v1 または otel-metrics-v1 である	メトリクスの検出には MCP listMetrics を使用します。
メトリクス API 呼び出しで 404 が返る	scripts/metrics/axiom-api ではなく、scripts/axiom-api（ダッシュボード用）を使用した	/v1/query/*、/v1/datasets には scripts/metrics/axiom-api を使用します。
0～1 の比率で、Statistic に 100% ではなく 1 が表示される	Percent enum は自動的に 100 倍されない	MPL で | map * 100 を実行し、その後 chart-add --unit "%" を指定します。
OTel ヒストグラムチャートに意味のない値が表示される	ヒストグラムがスカラーとして処理された	bucket … using interpolate_cumulative_histogram を使用します（または temporality に応じて _delta を使用します）。promql-to-mpl.md § Histogram translation を参照してください。
Grafana 移行後のフィルター／グループが誤ったサブセットを対象にする	description を確認せずに expr を読んだ、またはその逆	作成前に 5 つすべてのパネルフィールドを出力してください。reference/grafana-migration.md を参照してください。
PromQL のメトリクス名が見つからない	OTel の名前変更ルールを適用し忘れた	_total を削除し、ヒストグラムを分解し、単位を正規化してから、listMetrics で検証します。ラベルは逆タグ検出が必要です。grafana-migration.md § Name Mapping を参照してください。
MPL チャートが、PromQL ではフィルター／グループ化されていたディメンションをまたいで集計する	変換時にセレクターまたは by(...) を省略した	{label=…} はすべて where に、by(…) はすべて group by に変換します。reference/promql-to-mpl.md を参照してください。
パネルに、依頼されたものとは異なる値が表示された	保留せずに別の値に置き換えた	ブロッカーを記載した Note に置き換えてください。Compute or Defer を参照してください。
403「creating private dashboards」	API トークンで作成できるのは共有ダッシュボードのみ	owner は dashboard-assemble のデフォルト（X-AXIOM-EVERYONE）のままにします。
セクションの追加時に 400 invalid_dashboard が発生する	チャート JSON に sections または sectionId を独自に追加した	dashboard-assemble に --section / --section-collapsed を渡します。API を探る操作は行わないでください。

---

リファレンス

• reference/chart-config.md — すべてのチャート設定オプション（JSON）
• reference/metrics-mpl.md — Metrics/MPL チャートの仕様と検出スクリプト
• reference/smartfilter.md — SmartFilter/FilterBar の全設定
• reference/chart-cookbook.md — チャートタイプごとの APL パターン
• reference/layout-recipes.md — グリッドレイアウトとセクションのひな形
• reference/splunk-migration.md — Splunk パネルから Axiom へのマッピング
• reference/grafana-migration.md — Grafana パネルから Axiom へのマッピング（canonical-spec の投影、PromQL→MPL の参照情報、OTel の名称変更ルール）
• reference/promql-to-mpl.md — PromQL → MPL の変換ルール（セレクター、グループ化、rate、ヒストグラム、比率、逆タグ検出）
• reference/design-playbook.md — 意思決定を優先した設計原則
• reference/templates/ — すぐに使えるダッシュボード JSON ファイル

APL の構文については、https://axiom.co/docs/apl/introduction を参照してください。