テンプレート変数で「複製して使える」Datadog Dashboardを作る

この記事のポイント：複数システムへDatadog Dashboardを展開するとき、対象の違いを各Widgetの固定値として持たせず、Dashboard上部のテンプレート変数へ集約する設計を紹介します。変数の選び方、標準テンプレートと複製先の責任分担、データソース別の注意点、複製後の確認手順まで整理します。

はじめに

Datadog Dashboardを別のシステムや環境へ横展開するとき、既存のDashboardを複製して、WidgetのQueryに入っているシステム名、環境名、ホスト名などを書き換える方法があります。

Widgetが数個なら、この方法でも対応できます。しかし、Widgetが増えると、すべてのQueryを探して変更しなければなりません。一部だけ変更を忘れると、同じDashboardの中に別システムの値が混ざったり、条件に一致せず空表示になったりします。

横展開を前提にするなら、複製後に編集する場所を最初から限定しておく方が管理しやすくなります。

本記事では、個別システムの値を標準テンプレートへ固定せず、Dashboard上部のテンプレート変数で対象を切り替える設計を扱います。

テンプレート変数は「対象の差分」を上部へ集める

Datadogのテンプレート変数は、Dashboard上のWidgetをタグや属性で動的に絞り込んだり、グループ化したりする機能です。

例えば、envをテンプレート変数として用意し、WidgetのQueryで$envを参照すると、Dashboard上部で選択した環境を関連Widgetへ適用できます。対象を変更するたびに、各Widgetの編集画面を開く必要はありません。

横展開で重要なのは、変数を増やすことではなく、どの値を標準テンプレートに持たせ、どの値を複製先で決めるかを分けることです。

テンプレート変数を使っても確認作業は残ります。ただし、変更箇所をDashboard上部へ集約することで、「すべてのQueryを書き換えたか」ではなく、「変数が必要なWidgetへ適用されているか」を確認の中心にできます。

変数は「よく使うタグ」だけで選ばない

変数候補は、利用者が切り替えたい単位と、継続して管理できるタグの両方から選びます。

複数のDashboardで基本候補にしやすい軸は、システム、環境、ホスト、サービスです。ただし、これらを全Widgetへ一律に適用するわけではありません。クラウド環境では、AWSアカウントやOCIコンパートメントのように、クラウド側のデータを分ける軸が追加で必要になることもあります。

envやserviceはDatadogの複数機能をつなぐ代表的なタグですが、タグ名があるだけでは変数として安定しません。付与元によって同じキーに複数の値が付く場合や、データソースごとに値の表記が異なる場合があります。

値の管理者が決まっていないタグや、未付与のデータが多いタグを標準変数にすると、選択肢は表示されても期待したWidgetだけが空になる可能性があります。先にタグの付与ルールを整えるか、初期の標準変数から外して条件付き候補として扱います。

共通変数とデータソース固有の変数を分ける

すべてのWidgetへ、すべての変数を適用する必要はありません。

OSメトリクスでは、対象データに実際に付いているシステム、環境、ホスト、サービスのタグを組み合わせて絞り込めます。一方、クラウドIntegrationのメトリクスでは、クラウドアカウントやコンパートメントなど、別のディメンションが中心になる場合があります。

今回の設計では、AWS向けにaws_account、OCI向けにoci_compartmentをクラウド固有の候補としました。ただし、どのメトリクスにも必ず付くとは限りません。対象Integrationの実データを確認してから適用します。

例えば、次のように役割を分けます。

• Dashboard全体の対象：システム
• OSやAgentデータ：システム、環境、ホスト、サービス
• クラウドサービスのデータ：クラウドアカウントやコンパートメント
• Logs：実際に流入している属性やfacet
• Monitor一覧：Monitorへ付与したタグ

変数の並び順も、広い対象から狭い対象へそろえると選択しやすくなります。「システム → クラウドの範囲 → 環境 → ホスト → サービス」のように、利用者が対象を絞る順番を意識します。

この順番は製品仕様ではなく、運用設計です。対象環境で使わない変数を形式的に置くのではなく、各Widgetがどのデータとタグを参照するかに合わせて決めます。

標準テンプレートと複製先の責任を分ける

標準テンプレートには、個別システムの値を固定しません。変数の名前、タグキー、並び順、関連Widgetへの適用関係を定義し、既定値は全件を表す*などの汎用状態にします。

実際に利用するときは、標準テンプレートを複製し、複製先で次を設定します。

1. Dashboard名を対象に合わせる
2. 全体の対象となる変数の候補値を設定する
3. 最初に表示する既定値を設定する
4. クラウド固有の変数を対象環境に合わせる
5. 関連Widgetが同じ選択へ連動するか確認する

この分け方なら、標準テンプレートは再利用可能な構造を保ち、複製先はシステム固有の選択値だけを持てます。

一つのDashboardですべてのシステムを自由に切り替える方式もありますが、利用者や権限、既定表示、変更履歴をシステム単位で分けたい場合は、標準テンプレートを残してシステムごとに複製する方が分かりやすいことがあります。

テンプレート変数は「Dashboardを複製しないための機能」と決めつけず、標準と個別差分の境界を管理するために使います。

複製例：変更する場所をDashboard上部へ限定する

架空の標準Dashboardに、system_id、env、host、serviceの変数があり、各変数の既定値が*になっているとします。標準Dashboardには、特定システムの値を入れません。

このDashboardをシステムA向けに複製したら、複製先のsystem_idでは個別値の候補をsample-system-aに絞り、同じ値をDefault Valueにします。全値を問い合わせる*は、引き続き選択肢として扱います。envは利用する環境、hostとserviceは必要に応じて選べる状態にします。

Metric Widgetが$system_idを参照し、Monitor Summaryが同じ対象を検索できるよう設定されていれば、Dashboard上部の選択で関連Widgetをまとめて切り替えられます。一方、クラウド固有のWidgetには、そのメトリクスが持つアカウントやコンパートメントの変数だけを適用します。

複製後に個別のQueryを書き換えるのではなく、上部の変数設定、適用対象、既定表示を確認するのがこの方式の中心です。

Metric、Monitor、Logsで同じ書き方を使わない

同じタグを使っていても、データソースによってQueryや検索の書式は異なります。

Metric Queryでは、対象メトリクスに各タグが付いている場合に、テンプレート変数をスコープへ入れられます。

avg:system.cpu.idle{$system_id,$env,$host,$service} by {host}

Dashboard上部で値を選ぶと、変数を参照するMetric Widgetへ同じ絞り込み条件が反映されます。

Monitor Summary Widgetでは、何を検索対象にするかによって書式を分けます。Monitor自体へsystem_idタグを付けており、system_id変数がsystem_id:sample-systemの形へ展開される場合は、次のようにMonitorタグを検索できます。

tag:($system_id)

tag:(system_id:$system_id)のようにタグキーを重ねると、意図しない条件になる可能性があります。

一方、Monitorが監視するscopeやgroupで絞る場合は、公式ドキュメントの例にあるように、検索目的に合わせて書きます。

scope:$service
group:$env

Monitorタグ、監視scope、groupは同じものではありません。値だけが必要な場所では、Datadog公式ドキュメントにある$<変数名>.valueも確認します。

Logs、APM、RUMではタグだけでなくfacetや属性を変数にできます。UIから変数を追加するときに適用対象のWidgetを選び、実際のデータに同じ属性が存在するか確認します。

見た目が同じ変数でも、Metricタグ、Monitorタグ、Log属性は同じ保管領域ではありません。各データソースで検索結果を確認してから共通化します。

候補値と既定値は複製後に確認する

テンプレート変数には、ドロップダウンで選択を許可するAvailable Valuesと、Dashboardを開いたときに選択されるDefault Valueがあります。

標準テンプレートでAvailable Valuesを個別システムへ限定すると、そのテンプレートを別の環境へ展開しにくくなります。そのため、標準側では変数名、タグや属性、適用Widget、Queryの参照関係を定義し、複製先で対象に合わせてAvailable ValuesとDefault Valueを設定します。*はタグや属性の全値を問い合わせる選択肢であり、複製先の個別システムを示す既定値とは役割が異なります。

Available Valuesの設定とは別に、ドロップダウンへ表示される値は、Widgetが利用するデータソースと参照期間に基づいて作られます。Datadog公式ドキュメントでは、Metricsは直近48時間、その他の多くのデータソースはDashboardの時間範囲が参照されます。最近データが報告されていないタグ値は、ドロップダウンに表示されない場合があります。

値が見つからないときは、Metrics ExplorerやLog Explorerで正式なメトリクス名、属性、時間範囲を確認します。Default Valueを設定した後も、*へ戻した場合と特定値を選んだ場合の両方を確認します。

複製後の確認手順

Dashboardを複製した後は、次の順番で確認します。

1. Dashboard上部に必要な変数があり、広い対象から狭い対象の順に並んでいるか
2. 全体の対象となる変数のAvailable ValuesとDefault Valueを設定したか
3. Metric、Monitor、Logsなど、各データソースで変数の書式が合っているか
4. 変数を変更したとき、関連Widgetが同じ対象へ切り替わるか
5. 変数を適用しないWidgetが意図どおり残っているか
6. *、特定値、存在しない値で表示結果を確認したか
7. 空表示の場合、設計上の対象外か、追加確認が必要かを記録したか
8. Dashboard名、既定値、確認した期間、変更内容を記録したか

すべてのWidgetを表示させることだけを完了条件にしません。対象リソースが存在しないなど、空表示が想定内であれば、その理由と次の確認方法を残します。

まとめ

複製して使うDatadog Dashboardでは、個別システムの値を各Widgetへ固定せず、Dashboard上部のテンプレート変数へ対象の差分を集約します。

基本となる変数とデータソース固有の変数を分け、標準テンプレートには構造と参照関係、複製先には候補値と既定値を持たせることで、更新する場所を明確にできます。

また、Metric、Monitor、Logsでは検索書式とタグの保管領域が異なります。同じ変数名を使う場合でも、データソースごとに実データと検索結果を確認します。

テンプレート変数は、単なる絞り込み用のUIではありません。標準化する部分と環境ごとに変える部分の境界を管理する仕組みとして設計することが、Dashboardを安全に横展開するためのポイントです。

最後までお読みいただき、ありがとうございました。

参考資料

• Datadog公式ドキュメント：Template Variables
• Datadog公式ドキュメント：Querying
• Datadog公式ドキュメント：Monitor Summary Widget
• Datadog公式ドキュメント：Getting Started with Tags