Grafana可観測性
これは本番利用されたセルフホスト型スタックの実践例です。約60のダッシュボード、400以上のアラートルール、50のスクレイプジョブ、そしてログとトレースで構成され、すべてコードとして管理されています。以下の各ルールは、それを破ることで実際のインシデントが発生したために存在しています。なぜそうすべきかが説明されているので、エッジケースを判断することができます。
最初にモードを選択
- 学習(「教えて」、「説明して」、「これは何?」、「クイズして」):references/learning-path.md に従ってください。一度に1つのステージを教え、assets/lab/ のラボを実行してください。次のステージに進む前に理解度を確認してください。一度にすべてのステージを一気に説明しないでください。
- 構築(ダッシュボード、アラート、パイプライン、Terraform、またはロールアウト):以下のワークフローに従い、タスクに必要なリファレンスファイルのみを開いてください。
- 組織でのロールアウト計画:references/implementation-plan.md を参照してください。
スタックをひと目で
アプリケーション / ホスト / ネットワーク機器 / クラウドAPI
│ メトリクス (エクスポーター, /metrics) │ ログ (ファイル, docker, syslog) │ トレース (OTLP)
▼ ▼ ▼
Prometheus ◄── スクレイプ ── Grafana Alloy (収集: 検出、リラベル、編集、送信)
│ │ │
│ Loki Tempo
└────────────────┬──────────────────────────┴────────────────────────────────────┘
▼
Grafana ── ダッシュボード、Explore、アラート ──► コンタクトポイント (チャット、メール、オンコール)
▲
Terraform (フォルダ、データソース、ルール、ルーティング) + スクリプト (ダッシュボード) + git
厳格なルール
- コードが真実の源泉である。 アラートはTerraformを通じて変更し、ダッシュボードはgit管理下のジェネレータスクリプトまたはJSONで構築する。UIでのクリック操作は次のapplyで失われるか、さらに悪いことに次のapplyで暗黙的に元に戻される。
- applyの前に、2種類のドリフトを必ず確認する。 (a) 実際には存在するがコードにはないルール:対象を絞らないapplyはそれらを削除する。 (b) コードにはあるが実際に変更されたルール:applyはそれらをロールバックする。「変更なし」の計画は、Terraformが一度も見たことのないルールについては何の証明にもならない。references/as-code.md を参照。
- 保存した計画を守る。
terraform plan -outを実行し、意図していない あらゆる リソースに対するdelete/replaceを拒否する。フォルダにはprevent_destroyを設定する。Grafanaフォルダを削除すると、その中のすべてのダッシュボードとルールが削除される。 - サービスアカウントトークンを使用し、決して
admin:passwordを使わない。 状態がトークン認証で作成された場合、basic-auth でのapplyはフォルダ、コンタクトポイント、ポリシーツリーの削除と再作成を計画する。これにより、1回のapplyで59個のダッシュボードとルーティングツリー全体が一度に削除されたことがある。 - ルールに
notification_settings(コンタクトポイント)を決して設定しない。 設定されたルールはポリシーツリーを完全にバイパスする。重大度ルーティング、繰り返し間隔、ミュートタイミングを無視する。ある環境では、217ルール中196ルールがこれを行い、誰も気づかなかった。 - しきい値はPromQL内ではなく、Grafanaのしきい値ステージに設定する。
expr > 90を使用すると、正常なホストはシリーズを返さず、GrafanaはそれをOKではなくNoDataと解釈する。生の値をクエリし、ステージCで比較する。 - アクション可能性でルーティングし、繰り返し間隔を本当のレバーとして扱う。
severity(critical/warning/info)と、慢性的で既知の問題にはurgency=backlogを使用する。ほとんどのアラートノイズは、既に知られていることの再通知である。Criticalアラートは毎日、Warningは毎週、時間単位ではなく繰り返す。 - エスカレーションは遅延であり、サイレンスが受領確認である。 ページルートは約15分の
group_waitを使用するため、アラートがまだ発火中でサイレンスされていない場合にのみページングする。イベントスタイルのルールは、待機時間以上のkeep_firing_forが必要である。そうしないと、エスカレーションする前に解決してしまう。 - 監視を監視する。 評価失敗、通知配信失敗、抑制(サイレンス)されたアラート、停止したエクスポーター、停止したバックアップに注意する。サイレントなアラートシステムは、正常なシステムとまったく同じように見える。references/meta-monitoring.md を参照。
- 検証し、信頼しない。 すべてのパネルまたはアラートクエリを、作成前にデータソースに対して実行する。API書き込み後は、オブジェクトを読み戻し、変更が反映されていることを確認する。POST応答は、どのコンテンツが送信されたかを教えてくれない。複数の人や複数のセッション間での一致は検証ではない。1つのコマンドで実行すること。
変更のワークフロー
- パネルやアラートが答える質問と、それに対して誰が行動するかを明確にする。 誰もアラートに対して行動しない場合、それはアラートではなくダッシュボードパネルである。
- ExploreまたはデータソースプロキシAPIを通じてクエリを証明する。 データが返されること、グループ化やルーティングに使用するラベルが含まれていること、正常時の動作(空?ゼロ?)を確認する。
- コードで記述する: Terraformルールグループ、ダッシュボードジェネレータ、またはAlloy設定。 references/alerting.md または references/dashboards.md に従う。
- ドリフトを確認し、
terraform plan -out=tfplanを実行する。 すべての折りたたまれた~ブロック、特にgrafana_notification_policyを読む。なぜなら、すべてのアラートの送信先を決定するからである。 - 保存した計画をサービスアカウントトークンで適用する。 不明な場合は
-targetを使用する。 - APIから読み戻し、ルールが評価されていること(状態がError/NoDataでないこと)を確認し、アラートの場合は実際のコンタクトポイントへのエンドツーエンドのテストを実施する。
- ** 理由 とともにコミットする。** 選択が間違って見えるが意図的な場合には、コード内にコメントを残す。
完了の定義
アラートルール:Terraform内にあること。severity ラベルが設定されていること。サマリと説明テンプレートに影響を受けるホストまたはサービスと現在の値が含まれていること。no_data_state が意図的に選択されていること。for がフラップを防ぐのに十分な長さであること。ツリーによってルーティングされていること(ルールごとのコンタクトポイントはなし)。説明内にRunbookリンクまたは最初のステップがあること。エンドツーエンドでテスト済みであること。既存のルールと二重ページングしないこと。
ダッシュボード:git内にあること(生成済み、またはid/versionを削除してエクスポート)。正しいフォルダにあること。概要ハブからリンクされ、戻りリンクもあること。環境/ホスト用の変数があること。すべてのパネルに質問を投げかけたり答えたりするタイトルがあること。単位としきい値が設定されていること。リンクに keepTime が設定されていること。
新しいエクスポーターまたはデータソース:安定したラベル(env、team、service、role)でスクレイプされていること。フリートの up == 0 ルールでカバーされていること(別のルールを追加しない)。最終実行または鮮度メトリクスがある場合は、古さルールがあること。メタモニタリング監査に追加されていること。データソースには固定のuidがあること。
リファレンス一覧
| ファイル | 開くタイミング |
|---|---|
| learning-path.md | 教育や学習時、ラボを使って段階的に |
| architecture.md | コンポーネント、ラベル、保持期間、認証、HAの選択時 |
| queries.md | PromQLやLogQLの記述時、またはクエリが正しく見えない時 |
| dashboards.md | ダッシュボードの構築やレビュー時 |
| alerting.md | ルール、ルーティング、コンタクトポイント、サイレンス、疲労対策 |
| as-code.md | Terraform、API、バックアップ、ドリフト、復元 |
| meta-monitoring.md | 監視自体が機能していることの証明 |
| implementation-plan.md | Grafanaをチームや会社に導入する際 |
アセット:assets/lab/ はローカルDocker Composeラボです。 assets/terraform-starter/ は、安全なデフォルト設定が既に組み込まれたTerraformスタータースタックです。