datadog-dashboards

Datadog Dashboards

Datadog でダッシュボードを構築する際に求められる判断と、その決め方を説明します。各ルールでは、正すべき誤ったデフォルトを示します。モデルがすでに正しく処理できることについては、ルールを設けていません。

バージョンではなく、特定の日付に基づいています。 Datadog は継続的にリリースされるため、ここに記載した内容はすべて 2026 年 7 月に docs.datadoghq.com で確認済みです。バージョンに関係する内容を信頼する前に、必ず再確認してください。ここで挙げた非推奨の記述（q、default、is_read_only、week_before()）は、現在も解析されます。

Datadog MCP サーバーへの接続を前提としています（https://mcp.<site>/v1/mcp、toolsets=dashboards,widgets）。ウィジェットのスキーマは、このスキルではあえて再掲していません。get_widget_reference は呼び出し時点の最新スキーマを返すため、ここにコピーすると古くなってしまいます。サーバーに接続されていない場合は、先にセットアップしてください（ship-endpoint-follows-the-site）。このスキルでは Terraform や生の API による管理は扱いません。

適用する場面

次のような場合に、このスキルを使用してください。

• Datadog のダッシュボードを作成または編集する場合、あるいは他の人が作成したダッシュボードをレビューする場合。特に、グラフエディターではなくプログラムで組み立てられたボードでは、.as_count() の挙動の違いが問題になります。
• ウィジェットに使う Datadog クエリを記述する場合。スペース集計関数や修飾子を使うメトリクスクエリ、または search + compute + group_by を使う logs / spans / rum クエリが対象です。
• 可視化の種類を選ぶ場合、または「グラフがほしい」と依頼されても、実際にはランキング、単一の数値、エラーバジェットを求められている場合。
• ダッシュボードに誰も信頼していない数値が表示される場合、「No data」と表示されるパネルがある場合、または時間枠を変えると値が変わる場合。
• 対象の利用者が明示されずに「X のダッシュボードを作って」と依頼された場合。構築を始める前に、scope-ask-audience-and-decision の質問を行います。

このスキルの対象外：

• Terraform または生の Dashboard API によるダッシュボード管理（このスキルでは MCP サーバーを前提とします）
• モニターの作成や SLO の定義。ただし、依頼がそのどちらに当たるかの見極めについては、scope-not-every-question-is-a-dashboard で扱います。
• Datadog の計装：エージェントの設定、トレーサーのセットアップ、そもそもどのメトリクスを送信するかの判断
• Datadog 以外のオブザーバビリティプラットフォーム。このクエリのセマンティクスは他のプラットフォームには適用できません。

ルールのカテゴリ

#	カテゴリ	プレフィックス	対象
1	目的とスコープ	scope-	対象者、判断への活用、重複作成に代わる変数、ダッシュボードにすべきでないケース
2	アカウントの確認	disco-	クエリを実行する前にメトリクス、タグ、ファセットの存在を確認する
3	クエリのセマンティクス	query-	数値を返すものの、誤った結果になるクエリ
4	ウィジェットの選択	widget-	質問に合った可視化の選択、互換ではない組み合わせ
5	ダッシュボード JSON	json-	ウィジェットの検証では確認も説明もできないこと
6	レイアウトと読みやすさ	layout-	構成、表示タイプ、タイトル、サイズに関する Datadog 独自の標準
7	公開	ship-	書き込む前の検証とスモークテスト、リージョンのエンドポイント

クイックリファレンス

1. 目的とスコープ

• scope-ask-audience-and-decision — 最初のウィジェットを作る前に確認する 4 つの質問。答えはチャットではなく description に記載します。
• scope-one-dashboard-many-variables — サービスが 6 つあってもダッシュボードは 1 つです。変数のドロップダウンに表示されるのは、ボード内のウィジェットがクエリする値だけです。
• scope-clone-before-building — 1000 以上のインテグレーション向けにプリセットが用意されていますが、GET /dashboard では確認できません。一覧表示ではなく、検索してください。
• scope-not-every-question-is-a-dashboard — 「X が起きたら知らせて」はモニター、説明を中心とした内容はノートブックです。

2. アカウントの情報に基づく確認

• disco-never-invent-metric-names — 存在しないメトリクス名を指定すると、エラーではなく空のグラフが表示されます
• disco-read-type-and-unit-first — DogStatsD の increment() は RATE として保存されます。タイプによってモディファイアが決まり、単位によってタイトルが決まります
• disco-absence-is-not-proof — メトリクスは24時間後に検索対象から外れますが、15か月間保持されます
• disco-log-attributes-need-facets — ファセットのない属性ではグループ化できず、ファセットを一覧表示する API もありません

3. クエリのセマンティクス

• query-append-as-count-explicitly — 最も大きなデフォルトの違いです。 UI は .as_count() を追加しますが、API は追加せず、avg でロールアップします
• query-percentiles-require-distributions — p95: にはパーセンタイルが有効なディストリビューションが必要です。p95 の avg: はパーセンタイルではありません
• query-aggregate-before-dividing — .as_count() のない比率は、インターバルごとの比率を合計するため、150% と表示されることがあります
• query-gauge-gaps-are-interpolated — デフォルトでは、最大5分間の各欠損区間が補間された値で埋められます
• query-rollup-changes-the-number — 同じウィジェットでも、時間枠ごとに意味が変わります
• query-event-sources-take-objects — ログとスパンでは search+compute+group_by を使用します。interval の単位はミリ秒で、パーセンタイルには pc95 を使用します
• query-scope-syntax-does-not-mix — {env:prod AND !region:x} は無効です。$var の後にワイルドカードを付けても一致しません
• query-top-n-subtotals-are-partial — 上位リストの下に表示される合計は、表示中の行の合計です

4. ウィジェットの選択

• widget-match-the-question — 時系列グラフで答えられるのは1つの質問です。ランキング、単一値、差分には別のウィジェットを使用します
• widget-heatmap-is-not-distribution — 一方は x 軸が時間で、もう一方は数量です
• widget-reuse-alerting-primitives — しきい値の線を推測するのではなく、SLO とモニターを埋め込みます

5. ダッシュボード JSON

• json-type-strings-differ-from-ui-names — 円グラフは sunburst、テーブルは query_table、モニター概要は manage_status です
• json-queries-and-formulas-not-q — q とすべての *_query フィールドは非推奨です。data_source は profile_metrics ではなく profiles です
• json-layout-follows-reflow-type — reflow_type: auto の場合、layout は無視されるだけでなく、省略する必要があります
• json-template-variables-take-defaults — defaults は配列です。単数形の default は非推奨です
• json-dashboard-tags-are-constrained — 最大5個で、team: 形式にする必要があります。is_read_only は非推奨ですが、restricted_roles は非推奨ではありません

6. レイアウトと読みやすさ

• layout-put-widgets-in-groups — 「About」と「Overview」を最初に、ストリームを最後に配置し、背景上に何もむき出しで置かない
• layout-display-type-follows-metric-shape — 量にはエリア、数には棒、比較には折れ線を使う
• layout-let-datadog-render-units — すべての数式にエイリアスを付ける。軸に単位がすでに表示されています
• layout-size-for-the-medium — ウォールボードとトリアージボードは、同じダッシュボードにはできません

7. リリース

• ship-validate-before-upserting — 書き込み前にクエリをスモークテストし、ウィジェットごとに検証する
• ship-endpoint-follows-the-site — EU、AP、UK の組織にはそれぞれ専用の MCP ホストが必要です。GovCloud はサポートされていません

使い方

判断が必要になったら、該当するリファレンスファイルを読んでください。各ルールでは、修正対象となる誤ったデフォルトを示したうえで、標準的な形式を説明します。誤った方法が実際の落とし穴になる場合に限り、誤りと正しい例を対比します。

まず試してみる価値のある、3 つの近道を紹介します。

• 依頼に基づいてダッシュボードを作成していますか？ 何かを出力する前に、scope-ask-audience-and-decision、続いて disco-never-invent-metric-names を実行してください。どちらかを省くと、流暢でも役に立たないボードができてしまいます。

• 数値がおかしく見えるダッシュボードをレビューしていますか？ query-append-as-count-explicitly と query-percentiles-require-distributions から始めてください。この 2 つで、自信たっぷりに誤った Datadog パネルの大半を説明できます。また、どちらも UI に痕跡を残しません。

• 2025 年より前に書かれたダッシュボード JSON を移行していますか？ json-queries-and-formulas-not-q と json-template-variables-take-defaults は、今も解析できてしまう非推奨機能です。そのため、どこにも警告が表示されません。

• セクション定義 — カテゴリーの構成と並び順の理由

• ルールテンプレート — ルールを追加する場合に使用

• AGENTS.md — すべてのルールを横断する目次を自動生成します