ダッシュボード構築

設計思想

1. 意思決定を優先する。 すべてのパネルは、アクションにつながる質問に答える。
2. 概要 → ドリルダウン → 証拠。 広い視点から始まり、クリック/フィルタで絞込み、生ログで終わる。
3. 平均値ではなくレートとパーセンタイル。 平均値は問題を隠す。p95/p99 は露わにする。
4. シンプルは複雑に勝る。 1 パネル = 1 質問。グラフの装飾は不要。
5. データで検証する。 フィールドを推測しない。最初にスキーマを発見する。
6. 要求された値を計算するか、延期する。 パネルが計算できない場合は、障害を文書化した Note に置き換える。別の値を代替することは決してしない。説明があってもダメ。Compute or Defer を参照。

---

エントリーポイント

開始地点	ワークフロー
曖昧な説明	インテーク → データセットの種類を確認 → ブループリント設計 (APL または MPL) → パネルごとのクエリ → デプロイ
テンプレート	テンプレートを選択 → データセット/サービス/環境をカスタマイズ → デプロイ
Splunk ダッシュボード	SPL を抽出 → spl-to-apl で翻訳 → チャートタイプにマップ → デプロイ
Grafana ダッシュボード	正規パネル仕様を投影 (expr, legendFormat, unit, title, description) → PromQL を翻訳 → チャートタイプにマップ → デプロイ。reference/grafana-migration.md を参照。
探索	axiom-sre でスキーマ/シグナルを発見 → パネルに製品化

---

インテーク: 最初に聞くべきこと

1. 対象者と意思決定

   • オンコール対応のトリアージ? (高速リフレッシュ、エラーフォーカス)
   • チームの健全性? (日次トレンド、SLO 追跡)
   • エグゼクティブ報告? (週次サマリー、ハイレベル)

2. スコープ

   • サービス、環境、リージョン、クラスタ、エンドポイント?
   • 単一サービスか、クロスサービスビュー?

3. データセットの種類。 scripts/metrics/datasets <deploy> を実行して kind を確認。

   • otel:metrics:v1 → メトリクスデータセット、メトリクスパス に従う。
   • その他 → イベント/ログデータセット、APL パス に従う。

   メトリクスデータセットで getschema を実行しないでください。 エラーなしで 0 行返します。

   APL パス: ['dataset'] | where _time between (ago(1h) .. now()) | getschema でフィールドを発見。ステップ 4–5 に進む。

   メトリクスパス:

   • scripts/metrics/metrics-spec <deploy> <dataset> — MPL クエリの前に必須。
   • scripts/metrics/metrics-info <deploy> <dataset> metrics | tags | tags <tag> values で発見。
   • 発見が空の場合、--start を 7 日前で再試行 (スパースメトリクス)。
   • find-metrics <value> はメトリクス名ではなく、タグ値を検索 — 既知のエンティティ名でのみ使用。
   • メトリクス/MPL ブループリント にスキップ。

4. ゴールデンシグナル (APL パス)

   • トラフィック: リクエスト/秒、イベント/分
   • エラー: エラー率、5xx カウント
   • レイテンシ: p50、p95、p99 継続時間
   • 飽和: CPU、メモリ、キューの深さ、接続数

5. ドリルダウンディメンション (APL パス)

   • ユーザーは何でフィルタ/グループ化するか? (service、route、status、pod、customer_id)

---

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

データセットの種類に合致したブループリントを選択。

APL ブループリント (イベント/ログデータセット)

1. ひと目でわかる情報 (統計パネル)

「今壊れているか?」に答える単一の数値

• エラー率 (最後の 5 分)
• p95 レイテンシ (最後の 5 分)
• リクエスト率 (最後の 5 分)
• アクティブなアラート (該当する場合)

2. トレンド (TimeSeries パネル)

「何が変わった?」に答える時間ベースのパターン

• 時系列のトラフィック
• 時系列のエラー率
• 時系列のレイテンシパーセンタイル
• 比較用にステータス/サービス別にスタック

3. 分析 (Table/Pie パネル)

「どこを見るべき?」に答えるトップN 分析

• 失敗率の高いルートトップ 10
• エラーメッセージトップ 10
• エラー率が最悪のポッドトップ 10
• ステータス別のリクエスト分布

4. 証拠 (LogStream + SmartFilter)

「正確には何が起きたのか?」に答える生イベント

• エラーにフィルタされた LogStream
• サービス/環境/ルート用 SmartFilter
• 読みやすさのため主要フィールドを投影

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

バケットを作成するには align to $__interval using … を使用 — $__interval はダッシュボードランタイムに供給されます。ハードコードされたウィンドウは解像度が不足または過剰です。すべてのパイプラインを scripts/metrics/mpl-validate-chart で検証。それと chart-add --mpl の両方は、インライン時間範囲 ([1h..]) を拒否します。

例外: $__interval が空のバケットに丸まるスパースメトリクスの場合、より広い固定ウィンドウ (例: 1h) は許容されます。チャートで理由を文書化してください。

1. ひと目でわかる情報 (統計パネル)

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

• group using avg (ゲージ) または group using last (カウンター) を使用。
• metrics-info … metrics <m> info でメトリクスの unit を読み、chart-add --unit に渡す。比率メトリクス (0–1) は、--unit "%" の前に MPL で | map * 100 が必要。

2. トレンド (TimeSeries パネル)

時系列のトレンド — 「何が変わった?」

• align to $__interval using avg|sum|last。
• 低カーディナリティタグのみでグループ化 (≤10 系列/チャート)。
• --name に単位を埋め込む ("P95 Latency (ms)", "Memory (MiB)")。MPL で大きさをスケール (| map / 1048576 バイト → MiB)。

3. 分析 (TimeSeries または Table パネル)

エンティティごとの詳細 — 「どこを見るべき?」

• エンティティ (ホスト、ポッド、サービス) で分類されたメトリクス。
• シリーズ数を管理可能に保つためフィルタ。
• 1 パネル = 1 ディメンション。単一チャートにオーバーロードしない。

4. エンティティ状態 (TimeSeries または Table パネル)

ブール値/状態メトリクス — 「何がオン/オフ/アクティブか?」

• align to $__interval using last を使用。
• スパース状態メトリクスは、より広い固定間隔 (1h+) が必要な場合があります。

---

必須チャート構造

各チャートは一意のケバブケース id が必要 (error-rate, p95-latency)。すべてのレイアウト i がマッチするもの。chart-add --id と layout-pack <id>:… に同じ id を渡す。dashboard-assemble は出力前にクロスチェック。

---

チャートユニット設定

chart-add --unit に分かりやすい単位文字列を渡す ("%", "s", "ms", "B", "req/s")。スクリプトはチャートタイプごとに unit enum + customUnits サフィックスを選択。customUnits はラベルであり、フォーマッターではない — MPL で大きさをスケール (| map / 1048576 バイト → MiB、| map / 1000000 バイト → MB、| map * 100 で 0–1 比率 → パーセント)。メトリクスチャートの場合、metrics-info … metrics <m> info からソースユニットを読み、渡す。内部仕様 (エージェントが jq でマージする可能性のある高度なオプション): reference/chart-config.md。

---

Compute or Defer

各パネルは要求された量を計算するか、障害を文書化した Note に置き換えられます。別の量を代替することは決して許容されない — 免責事項は行動する人に届きません。

延期テンプレート (chart-add --type Note を使用):

**Deferred — blocked by:** <ワンライン理由>。

**Original spec:** <パネルが計算すべきもの、ディメンション、単位>。

**To unblock:** <修正へのポインタ>。

一般的な障害: 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_   // 制限あり
| summarize count() by user_id                    // 無制限 — 避ける

フィールドエスケープ

ドットを含むフィールドはブラケット記法が必要:

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

名前にドット (階層ではなく) があるフィールドはエスケープが必要:

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

レシピ

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

---

レイアウト構成

layout-pack は 12 列グリッドに行優先でチャートをパック (タイプ別デフォルト: Statistic 3×3、TimeSeries 6×4、Table 6×5、LogStream 12×6、Note 12×2)。必要に応じて id:WxH で上書き。セクションブループリント: reference/layout-recipes.md。命名とパネル順序の規則: reference/design-playbook.md。

---

ダッシュボード設定

リフレッシュレート

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 を stdout に出力。APL vs MPL を分割; MPL クエリはインライン時間範囲チェック; ユニットフィールドはチャートタイプごとに適用。
scripts/layout-pack <id>:<Type|WxH> ...	レイアウト JSON 配列を stdout に出力。12 列グリッドに行優先; タイプ名はデフォルトサイズにマップ。
scripts/dashboard-assemble --name … --datasets … --layout F.json [opts] CHART_FILES…	チャートファイル + レイアウトから完全なダッシュボード JSON を構成。エンベロープを所有 (owner, schemaVersion, qr- プレフィックス、refreshTime 検証、id クロスチェック)。
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)	単一チャートをパッチ
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 <deploy> <dataset>	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 を使用。PATCH /v2/dashboards/uid/{uid}/charts/{chartId} を、chart リクエストフィールド配下の JSON マージパッチで呼び出します。

パッチファイルは変更するチャートフィールドのみを含む:

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

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

dashboard-get でダッシュボードを取得した後、楽観的ロック用に --version <version> を使用。--overwrite は最後の書き込みが勝つ動作の場合のみ使用。レイアウト変更、複数チャート編集、ダッシュボードメタデータ、owner、リフレッシュ間隔、時間ウィンドウ更新には引き続き dashboard-update を使用。

ワークフロー

chart-add, layout-pack, dashboard-assemble は JSON 形状を所有。各チャートは独自のテンポラリファイル内に存在。チャート形状が再びエージェントのコンテキストに入ることはありません。

1. スキーマを発見 (イベント用 axiom-sre / getschema; メトリクス用 metrics-spec + metrics-info)。
2. 各パネルクエリを記述。APL は明示的な時間フィルタで axiom-sre により検証; MPL は scripts/metrics/mpl-validate-chart により検証。
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 CHART_FILES…。
6. dashboard-validate その後 dashboard-create (または dashboard-update)。
7. dashboard-link で URL — 手作業で構築しない。

---

兄弟スキル統合

• spl-to-apl — Splunk SPL → APL (timechart → TimeSeries、stats → Statistic/Table)。reference/splunk-migration.md を参照。
• axiom-sre — getschema によるスキーマ発見、ベースライン探索。
• query-metrics — メトリクスデータセット/タグ/値の発見; scripts/metrics/ 配下に同じスクリプトをベンダリング。

---

テンプレート

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 行を返す	データセットは otel:metrics:v1	メトリクス発見に scripts/metrics/metrics-info を使用。
メトリクス発見が空を返す	スパースメトリクスが 24h デフォルトウィンドウ外	--start を 7 日前で再試行。
メトリクス API 呼び出しから 404	scripts/axiom-api (ダッシュボード) を使用した	メトリクス API に scripts/metrics/axiom-api を使用。
統計が 0–1 比率の 100% の代わりに 1 を表示	Percent enum は自動乗算しない	MPL で `
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 を削除、ヒストグラムを分解、ユニットを正規化; metrics-info で検証。ラベルはリバースタグ発見が必要。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) のままにする。

---

リファレンス

• reference/chart-config.md — すべてのチャート設定オプション (JSON)
• reference/metrics-mpl.md — メトリクス/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 マッピング (正規スペック投影、PromQL→MPL ポインタ、OTel 名前変更ルール)
• reference/promql-to-mpl.md — PromQL → MPL 翻訳ルール (セレクタ、グループ化、レート、ヒストグラム、比率、リバースタグ発見)
• reference/design-playbook.md — 意思決定優先設計原則
• reference/templates/ — 使用可能なダッシュボード JSON ファイル

APL 構文について: https://axiom.co/docs/apl/introduction