datadog-design-dashboard

Datadog ダッシュボードの設計

適切なウィジェットタイプ、グループ構成、再利用可能なテンプレート変数を使って、全体的な健全性のシグナルから詳細な診断まで、明確な流れを伝えるダッシュボードレイアウトを設計します。

重要：まず必ず pup dashboards list --agent を使って既存のダッシュボードを確認してください。同じサービスまたは目的のダッシュボードがすでにある場合は、新しいダッシュボードを作成せず、既存のものを更新してください。関連するダッシュボードがない場合、またはユーザーが明示的に新規作成を求めた場合にのみ、新しいダッシュボードを作成してください。

基本方針：このスキルで紹介するフレームワーク、レイアウト、ウィジェットガイドは出発点であり、厳格なルールではありません。製品やビジネスはそれぞれ異なります。まずドメインを理解し、そのうえでフレームワークを適合させてください。優れたダッシュボードは、汎用テンプレートの指示ではなく、ビジネスの実態を反映します。

---

ヒアリング

まず、モードを判断します。

• 設計モード — ユーザーがダッシュボードの作成または再設計を希望している場合 → 設計に関する質問をしてから、全ワークフローを実行します
• 監査モード — ユーザーが再設計の意図なく既存のダッシュボードの確認を希望している場合 → 監査に進みます

設計に関する質問

次の項目がすべてすでに指定されている場合は省略します：ダッシュボードの目的、対象者、データソース、テンプレート変数の要件、ダッシュボード戦略。

1. 目的 — 「このダッシュボードは何のためのものですか？サービス概要、インフラストラクチャ、経営層向け KPI、デバッグ、SLO の追跡などでしょうか？」
2. 対象者 — 「誰が使いますか？オンコールエンジニア、プラットフォームチーム、経営層、または複数の対象者でしょうか？」
3. データソース — 「どの Datadog 製品を使いますか？メトリクスのみ、APM + メトリクス、ログ + メトリクス、それともフルスタックでしょうか？」
4. 範囲 — 「単一のサービス、複数のサービス群、インフラストラクチャ全体のいずれが対象ですか？」
5. ダッシュボード戦略 — 「サービスごとにダッシュボードを作成しますか、それとも統合ビューにしますか？」— 判断の参考として、references/layouts.md のトレードオフを共有してください。決めかねている場合は、次のように質問します。「障害発生時、チームは一度に1つのサービスを調査しますか、それともすべてのサービスを同時に確認する必要がありますか？」
6. 既存のダッシュボード — 「監査または再設計する既存のダッシュボードはありますか？」ある場合は、設計前に pup dashboards get <id> --agent で取得します。

監査に関する質問

次の項目がすべてすでに指定されている場合は省略します：ダッシュボード ID または URL、サービス名またはチームのコンテキスト。

次の場合は必ずヒアリングします：ダッシュボード ID が指定されていない場合、または関連する可能性のあるダッシュボードが複数ある場合。

1. ダッシュボード — 「どのダッシュボードを確認しますか？ダッシュボード ID、URL、または検索用のサービス名をお知らせください。」
2. ビジネスコンテキスト — 「このサービスが顧客にどのような価値を提供しているか教えていただけますか？製品を理解するために参照できるコードベースやドキュメントはありますか？」
   • 影響：ドメインを理解することで、一般的なルールに従っているかどうかだけでなく、適切なメトリクスが追跡されているかどうかに焦点を当てたレビューができます
3. 重点項目 — 「特に重点を置いてほしい項目はありますか？（A）全体的なレビュー、（B）アラートのしきい値のみ、（C）ビジネスセクション、（D）レイアウトと読みやすさ」
   • 指定がない場合は、全体的なレビューを行います

---

ドメインの把握

設計モードに適用されます。監査のみの場合はスキップしてください。

設計を始める前に、何を対象にオブザーバビリティを構築するのかを把握してください。重要なメトリクスは、製品やビジネスの状況によって大きく異なります。

ユーザーに尋ねること：

• 「製品と、このサービスがビジネスにどのような価値を提供しているか教えていただけますか？ 顧客がこのサービスを利用するとき、どのような体験をしますか？」
• 「このサービスにとって、調子の悪い日はどのような状態ですか？ 何が壊れ、顧客にはどのような影響がありますか？」
• 「サービスとその依存関係を理解するために読めるコードベース、アーキテクチャドキュメント、README ファイルはありますか？」

ユーザーがコードベースを案内してくれた場合：内容を読みます。エントリーポイント、API ルート、データベースモデル、キューのコンシューマー、外部サービス呼び出しを確認します。コードを理解すれば、一般的な RED／USE シグナルではなく、本当に重要なメトリクスを選ぶための背景を把握できます。

ユーザーがビジネスについて説明してくれた場合：その情報を使って、Business（B）セクションを調整します。E コマースサービスではチェックアウトの成功率が重要です。メッセージングサービスでは配信レイテンシーが重要です。決済サービスでは取引の完了が重要です。「リクエスト率」や「エラー率」のような一般的な指標は出発点ですが、顧客に見える成果に対応したメトリクスにこそ、本当の価値があります。

次の場合はドメインの把握をスキップします：これまでの会話ですでにサービスについて十分に理解している場合、またはユーザーから詳細な仕様が提示されている場合。

必須条件：Business グループを設計する前に、このサービス固有のドメイン上の成果を少なくとも 3 つ、プロダクトマネージャーにもわかる平易な言葉で挙げられる必要があります。例：「注文完了」、「決済完了」、「メッセージ配信」。挙げられない場合は、先にユーザーに尋ねてください。代わりにトランスポート層のメトリクス（gRPC エラー率、HTTP リクエスト率）を使わないでください。これらは P であり、B ではありません。references/widgets.md の B に関する注意事項を参照してください。

---

設計

既存のダッシュボードのレビューのみを希望する場合は、監査に進んでください。

1. 既存のコンテキストを収集する

pup dashboards list --agent
pup dashboards get <dashboard-id> --agent

既存のダッシュボードを監査する場合は、再設計する前にまず定義を取得し、現在の構成を分析してください。

2. 利用可能なテレメトリーを調査する

ウィジェットを設計する前に、そのサービスで実際に利用できるメトリクスとタグ値を確認してください。これにより、存在しないメトリクスを前提に設計したり、クエリで誤ったタグ値を使用したりするのを防げます。

# See what metrics are available for the service
pup metrics list --filter="<service-name>.*" --agent

# Verify the service tag is active and see what metrics are flowing
pup metrics list --filter="trace.*" --tag-filter="service:<service-name>" --agent

ウィジェットのクエリを記述する際は、ここで見つけた実際のメトリクス名とタグ値を使ってください。推測したり、捏造したりしないでください。想定していたメトリクスが見つからない場合は、それを使ったウィジェットを作成する前にユーザーに伝えてください。

これはすべてのクエリタイプに適用されます：メトリクスクエリ、APM スパンフィルター（operation_name、resource_name、スパンタグ）、ログフィルター。 references/widgets.md の **Configuration** セクションでは、JSON の構造とフィールドの制約のみを説明しています。特定のクエリを指定するものではありません。使用する前に、必ず pup で実際のフィルター値を確認してください。

3. フレームワークを選ぶ

ダッシュボードの目的に合ったフレームワークを選びます。メトリクスの詳細な対応関係とグループ構成については、references/frameworks.md を読んでください。

目的	フレームワーク
サービス概要	RED（レート、エラー、継続時間）
インフラストラクチャ	USE（使用率、飽和度、エラー）
経営／ビジネス	ゴールデンシグナル
SLO の追跡	SLI／SLO
デバッグ	ドリルダウン

4. レイアウトを設計する

ドメインに関する理解と選択したフレームワークに基づいて、グループ構成を設計し、ウィジェットを選択します。設計する前に、次のリファレンスを確認してください。

• layouts.md — テンプレート変数の規則、グループ構成のパターン、ダッシュボード戦略のトレードオフ、グリッドのサイズ設定、アンチパターン
• widgets.md — ウィジェット選択ガイド、表示オプション、サイズ設定、命名規則
• thresholds.md — アラートしきい値マーカー、しきい値との近接性、Y 軸の設定

5. タブを検討する

ダッシュボードにトップレベルのグループが 7 つ以上ある場合、タブによってスクロールの負担を軽減できるか検討します。構成パターン、JSON スキーマ、よくある間違いについては、references/tabs.md を確認してください。

既存のダッシュボードにタブを追加する前に、すべてのウィジェット ID を監査して重複がないことを確認してください。タブを使うと、重複の検証が厳格になります。

6. 設計出力を作成する

次のテンプレートを使って設計を提示します。

# Dashboard Design: [Dashboard Title]

## Purpose
[1-2 sentences: what this monitors, who uses it]

## Template Variables
| Variable | Tag | Default |
|----------|-----|---------|
| ... | ... | `*` |

## Layout

### Group: [Group Title]
| Widget | Type | Query/Metric | Width | Alert Threshold |
|--------|------|-------------|-------|----------------|
| ... | ... | ... | ... | ... |

[Repeat for each group]

---

監査

どちらのモードにも適用されます。設計後に実行するか、既存のダッシュボードを監査する場合は直接実行してください。

基本原則は、グラフにはアラートしきい値を設定して掲載する価値を持たせること、しきい値を通常のトラフィックに近づけること、ビジネスセクションを最上部に設けること、そしてサービスに関する知識がまったくない人でもダッシュボードを読み取れることです。

これらは指針であり、厳格なチェックリストではありません。プロダクトとビジネスの状況に応じて判断してください。デプロイイベントのような状況を把握するためのメトリクスは、しきい値がなくても掲載する価値がある場合があります。通常とは異なるトラフィックパターンを持つサービスでは、異なる近接性の基準が必要になる場合があります。

1. ダッシュボードを取得する

# If given a service name, list all dashboards and identify the relevant one by title
pup dashboards list --agent

# If given a URL, extract the dashboard ID from the path (e.g., /dashboard/abc-def-ghi/...)

# Get the full dashboard definition (includes the dashboard URL in the response)
pup dashboards get <dashboard-id> --agent

# Verify real metric names exist
pup metrics list --filter="trace.http.request.*" --agent

レスポンスを解析し、すべてのウィジェット、グループ、およびそれぞれの設定を一覧化します。

2. ウィジェット一覧を作成する

一覧化する前に、ウィジェットのプレフィックス体系全体について references/widgets.md を確認してください。

ダッシュボード内のすべてのウィジェットを一覧化します。

ウィジェットタイトル	プレフィックス	種類	グループ	アラートしきい値あり	しきい値	備考
...	I0/P1/D0/B0/—	...	...	...	...	...

時系列ウィジェットとクエリ値ウィジェットを中心に確認します。これらはアラートしきい値マーカーの主な候補です。

3. アラートしきい値を監査する

しきい値マーカーの原則、設定の詳細、指摘事項の形式については、references/thresholds.md を確認してください。

各時系列ウィジェットについて、次を確認します。

• マーカー／しきい値ラインが設定されているか
• 見やすいようにマーカーが赤で表示されているか
• しきい値が実際のモニター／アラートに対応しているか

4. しきい値との近接性を監査する

近接性のガイダンス、Y 軸の設定ルール、指摘事項の形式については、references/thresholds.md を確認してください。

しきい値がある各ウィジェットについて、次を確認します。

• 通常の値の範囲はどの程度か
• しきい値はどこに設定されているか
• 通常のラインとアラートラインの間に、過剰な空白がないか
• Y 軸は自動スケーリングか、明示的に設定されているか

5. ビジネスセクションを監査する

原則：ダッシュボードの最上部に専用のビジネス（B）グループを設け、障害をすぐに特定できるよう、重要なメトリクスを5～8個配置します。ビジネスメトリクスは、顧客に見える成果を示すものであり、インフラやドメイン内部の指標ではありません。メトリクスは、汎用的なトラフィックやエラー率ではなく、プロダクトのビジネストランザクションを反映する必要があります。

確認事項：

• ビジネスグループ（「Business」、「B」、または同等の名前）はありますか？
• ダッシュボードの最初のグループになっていますか？
• ウィジェットでは B0-N: プレフィックスを使用していますか？
• 顧客に見える成功率、主要なトランザクションフロー、SLA に影響するレイテンシを網羅する5～8個のメトリクスが含まれていますか？
• ダッシュボードを開いてから5秒以内に、「顧客に影響が出ているか」を判断できますか？
• B の誤分類チェック：B プレフィックスが付いた各ウィジェットについて、「トランスポートプロトコルを知らなくても、プロダクトマネージャーが解釈できるか」と確認します。できない場合、配置場所にかかわらず、それは B ではなく P です。gRPC エラー率、HTTP リクエスト率、キュー深度などが該当します。問題を指摘し、適切なプラットフォームグループへの移動を推奨します。

指摘事項の形式：

#### Business Section Audit

**Status**: MISSING / INCOMPLETE / OK

**Current state**: [Description of what exists]

**Recommended metrics** (if missing or incomplete):
1. B0: Key transaction success rate (are critical flows completing?)
2. B0: Customer-facing error rate (are requests failing for customers?)
3. B1: API p99 latency (are responses slow for customers?)
4. B1: Total request rate (are we receiving traffic?)
5. B2: Queue depth or processing lag (is async work backing up?)
6. B2: Key business event throughput (e.g. orders created, payments processed)

6. 予備知識ゼロの閲覧者テストを適用する

原則：サービスについて何も知らない人でも、赤いインジケーターを見て問題を見つけられるようにします。

評価項目：

• ウィジェットのタイトルを読まずに、10秒以内に問題を特定できますか？
• すべてのグラフで、しきい値が赤い線として表示されていますか？
• クエリ値ウィジェットに条件付き書式（緑／黄／赤）が適用されていますか？
• グループ名は内容を明確に表していますか？
• ランブックへのリンクやチームの担当情報を記載したノートウィジェットはありますか？

指摘事項の形式：

#### Zero-Knowledge Readability Audit

| Check | Status | Finding |
|-------|--------|---------|
| Problems visible in <10s | FAIL | No red lines on 8 of 12 graphs |
| Conditional formatting on QV widgets | PARTIAL | 2 of 4 QV widgets have thresholds |
| Group names self-explanatory | OK | All groups use clear names |
| Runbook/ownership note | MISSING | No note widget with team info |

7. タブの構成を監査する

ダッシュボードにトップレベルのグループが7個以上ある場合、タブが使われているか確認します。references/tabs.md を参照してください。

• 関連するグループは、可観測性レイヤーごとにタブにまとめられていますか？
• タブ名は、答える質問を反映していますか（サービスの健全性、プラットフォーム、インフラストラクチャなど）？
• トップレベルのウィジェットはすべて、いずれか1つのタブに割り当てられていますか？

8. 監査レポートを作成する

すべての指摘事項を構造化されたレポートにまとめます。

# Dashboard Audit: [Dashboard Title]

**Dashboard ID**: [id]
**URL**: [url]
**Review date**: [date]

## Summary

[2-3 sentence summary: overall health of the dashboard, critical issues count]

## Critical Issues

[List issues that must be fixed before the dashboard is production-ready]

## Alert Threshold Audit
[From step 3]

## Threshold Proximity Audit
[From step 4]

## Business Section Audit
[From step 5]

## Zero-Knowledge Readability Audit
[From step 6]

## Recommended Actions

### Must Fix
1. [Action item with specific widget and group reference]

### Should Fix
1. [Action item]

### Nice to Have
1. [Action item]

---

品質原則

• ウィジェットのクエリでは、pup metrics list --agent で確認した実在のメトリクス名を使用している — 存在しないメトリクス名を作らない
• ダッシュボードは実際のプロダクトとビジネスを反映している — ドメインに合わせたメトリクスを使う
• ダッシュボードのタイトルは [service] Purpose のパターンに従っている — 「Dashboard」のサフィックスや、タイトル内の環境名は使わない
• JSON の title フィールドを更新している（ファイル名だけでなく） — タイトルを変更したら再デプロイする
• テンプレート変数はダッシュボードの種類に合っている — references/layouts.md を参照
• ウィジェットのクエリでは、pup metrics list --agent で確認したテンプレート変数のスコープを使用している — 環境、サービス、ホストの値をハードコードせず、ダッシュボードの種類に適した変数セットを使う（references/layouts.md を参照）
• ビジネスグループに、サービスの顧客に見える成果に合わせた B プレフィックス付きメトリクスが5～8個ある
• グループは全体から詳細へ（ビジネス → 概要 → 詳細）の順に並んでいる
• すべてのウィジェットタイトルでレイヤー優先度のプレフィックスを使用している（I0:、P1:、D0:、B0: など）— references/widgets.md を参照
• ウィジェットタイトルはセンテンスケースを使い、グループ名を繰り返していない
• アラート対象のメトリクスを表示する時系列ウィジェットには、アラートしきい値のマーカー（赤い線）がある — references/thresholds.md を参照
• しきい値は通常時のトラフィックに近い — 余白が過剰にならないようにする
• 予備知識ゼロでも読み取れる — サービスの知識がない人でも、赤いインジケーターを見て問題を見つけられる
• クエリ値ウィジェットに条件付き書式（緑／黄／赤）が設定されている
• すべてのメトリクスに存在意義がある — 急上昇した際に、誰かが対応できる
• すべての監査指摘に、具体的なウィジェット名とグループへの参照が含まれている
• 推奨する対応は優先度（必須／推奨／できれば）ごとに分類されている
• 監査レポートにダッシュボードの URL が含まれている

リファレンス

• オブザーバビリティフレームワーク — RED、USE、ゴールデンシグナル、SLI/SLOとメトリクスマッピング
• レイアウトと構成 — テンプレート変数、グループパターン、ダッシュボード戦略、グリッドサイズ、アンチパターン
• ウィジェット — ウィジェットのプレフィックスシステム、種類、表示オプション、サイズ設定、命名規則
• アラートのしきい値 — しきい値マーカー、近接ガイド、Y軸の設定
• タブ — ダッシュボードのタブ構成、JSONスキーマ、@Nの位置参照、よくある間違い