grafana-可観測性

Grafana可観測性スタック(Prometheusメトリクス、Lokiログ、Tempoトレース、Alloy収集、Grafanaダッシュボードとアラート)をコードとしてTerraformで管理するための学習、設計、構築、運用を行います。Grafana、PromQL、LogQLの学習や指導、監視のセットアップ、ダッシュボードやアラートルール、通知ポリシー、コンタクトポイント、Alloyパイプライン、Grafana Terraformの作成やレビュー、あるいはノイズが多い、サイレント、NoDataでスタックしている、誰にも届いていないアラートのデバッグ時に使用します。

grafana-可観測性 とは?

このスキルは、本番運用されたGrafana可観測性スタックのベストプラクティスを提供します。このスタックは約60のダッシュボード、400以上のアラートルール、50のスクレイプジョブ、そしてログとトレースで構成され、すべてコードとして管理されています。主要なユースケースは3つあります。(1)学習モードでは、学習パスに従って段階的に教え、ラボで実践します。(2)構築モードでは、ダッシュボード、アラート、パイプライン、Terraform構成をコードで作成し、確立されたワークフロー(クエリの証明、コード化、ドリフトチェック、適用、読み返し、コミット)に従います。(3)ロールアウト計画では、組織全体への導入を支援する実装計画を提供します。このスキルは、Terraformをコードの真実の源泉として使用し(UIでの手動変更は次の適用で失われるか元に戻される)、ダッシュボードはgit管理下のジェネレータスクリプトまたはJSONで構築することを強制します。設定変更には厳格なドリフトチェックが必須であり、サービスアカウントトークンによる認証、ルール内での直接の通知設定回避、しきい値の適切な設定、アクション可能性に基づくルーティングなど、10の厳格なルールを定義しています。これらすべてのルールは、実際のインシデントから生まれたものです。また、監視自体を監視する(メタモニタリング)ことの重要性も強調しています。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/louij2/grafana-observability-skill/tree/HEAD/.github/skills/grafana-observability

Installed? Explore more 生産性&コラボレーション skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

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

詳細:references/architecture.md

厳格なルール

  1. コードが真実の源泉である。 アラートはTerraformを通じて変更し、ダッシュボードはgit管理下のジェネレータスクリプトまたはJSONで構築する。UIでのクリック操作は次のapplyで失われるか、さらに悪いことに次のapplyで暗黙的に元に戻される。
  2. applyの前に、2種類のドリフトを必ず確認する。 (a) 実際には存在するがコードにはないルール:対象を絞らないapplyはそれらを削除する。 (b) コードにはあるが実際に変更されたルール:applyはそれらをロールバックする。「変更なし」の計画は、Terraformが一度も見たことのないルールについては何の証明にもならない。references/as-code.md を参照。
  3. 保存した計画を守る。 terraform plan -out を実行し、意図していない あらゆる リソースに対する delete/replace を拒否する。フォルダには prevent_destroy を設定する。Grafanaフォルダを削除すると、その中のすべてのダッシュボードとルールが削除される。
  4. サービスアカウントトークンを使用し、決して admin:password を使わない。 状態がトークン認証で作成された場合、basic-auth でのapplyはフォルダ、コンタクトポイント、ポリシーツリーの削除と再作成を計画する。これにより、1回のapplyで59個のダッシュボードとルーティングツリー全体が一度に削除されたことがある。
  5. ルールに notification_settings(コンタクトポイント)を決して設定しない。 設定されたルールはポリシーツリーを完全にバイパスする。重大度ルーティング、繰り返し間隔、ミュートタイミングを無視する。ある環境では、217ルール中196ルールがこれを行い、誰も気づかなかった。
  6. しきい値はPromQL内ではなく、Grafanaのしきい値ステージに設定する。 expr > 90 を使用すると、正常なホストはシリーズを返さず、GrafanaはそれをOKではなくNoDataと解釈する。生の値をクエリし、ステージCで比較する。
  7. アクション可能性でルーティングし、繰り返し間隔を本当のレバーとして扱う。 severity(critical/warning/info)と、慢性的で既知の問題には urgency=backlog を使用する。ほとんどのアラートノイズは、既に知られていることの再通知である。Criticalアラートは毎日、Warningは毎週、時間単位ではなく繰り返す。
  8. エスカレーションは遅延であり、サイレンスが受領確認である。 ページルートは約15分の group_wait を使用するため、アラートがまだ発火中でサイレンスされていない場合にのみページングする。イベントスタイルのルールは、待機時間以上の keep_firing_for が必要である。そうしないと、エスカレーションする前に解決してしまう。
  9. 監視を監視する。 評価失敗、通知配信失敗、抑制(サイレンス)されたアラート、停止したエクスポーター、停止したバックアップに注意する。サイレントなアラートシステムは、正常なシステムとまったく同じように見える。references/meta-monitoring.md を参照。
  10. 検証し、信頼しない。 すべてのパネルまたはアラートクエリを、作成前にデータソースに対して実行する。API書き込み後は、オブジェクトを読み戻し、変更が反映されていることを確認する。POST応答は、どのコンテンツが送信されたかを教えてくれない。複数の人や複数のセッション間での一致は検証ではない。1つのコマンドで実行すること。

変更のワークフロー

  1. パネルやアラートが答える質問と、それに対して誰が行動するかを明確にする。 誰もアラートに対して行動しない場合、それはアラートではなくダッシュボードパネルである。
  2. ExploreまたはデータソースプロキシAPIを通じてクエリを証明する。 データが返されること、グループ化やルーティングに使用するラベルが含まれていること、正常時の動作(空?ゼロ?)を確認する。
  3. コードで記述する: Terraformルールグループ、ダッシュボードジェネレータ、またはAlloy設定。 references/alerting.md または references/dashboards.md に従う。
  4. ドリフトを確認し、terraform plan -out=tfplan を実行する。 すべての折りたたまれた ~ ブロック、特に grafana_notification_policy を読む。なぜなら、すべてのアラートの送信先を決定するからである。
  5. 保存した計画をサービスアカウントトークンで適用する。 不明な場合は -target を使用する。
  6. APIから読み戻し、ルールが評価されていること(状態がError/NoDataでないこと)を確認し、アラートの場合は実際のコンタクトポイントへのエンドツーエンドのテストを実施する。
  7. ** 理由 とともにコミットする。** 選択が間違って見えるが意図的な場合には、コード内にコメントを残す。

完了の定義

アラートルール: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.mdPromQLやLogQLの記述時、またはクエリが正しく見えない時
dashboards.mdダッシュボードの構築やレビュー時
alerting.mdルール、ルーティング、コンタクトポイント、サイレンス、疲労対策
as-code.mdTerraform、API、バックアップ、ドリフト、復元
meta-monitoring.md監視自体が機能していることの証明
implementation-plan.mdGrafanaをチームや会社に導入する際

アセット:assets/lab/ はローカルDocker Composeラボです。 assets/terraform-starter/ は、安全なデフォルト設定が既に組み込まれたTerraformスタータースタックです。

関連スキル