Community生產力與協作github.com

grafana-observability

學習、設計、建構並運行以程式碼管理(Terraform)的 Grafana 可觀測性堆疊(Prometheus 指標、Loki 日誌、Tempo 追蹤、Alloy 收集、Grafana 儀表板與告警)。

grafana-observability 是什麼?

此技能提供一個完整的生產級 Grafana 可觀測性堆疊實作指南,涵蓋約 60 個儀表板、400 多條告規則、50 個抓取任務,以及日誌與追蹤,全部以 Terraform 作為基礎架構即程式碼管理。每個規則背後都有真實的運維事故作為支撐,確保最佳實務的有效性。技能支援學習模式(逐步教學與實驗室環境)、建構模式(儀表板、告警、Alloy 管線、Terraform 設定)以及規劃導入模式(組織級實作計畫)。關鍵規範包括:程式碼為唯一真相來源、應用前檢查漂移、保護已儲存的 Terraform 計畫、使用服務帳號 Token、避免將通知設定直接掛在規則上、將閾值放在 Grafana 的 threshold 階段而非 PromQL 內、根據可行動性路由告警、延遲升級與靜音作為確認、監控監控系統本身,以及務必驗證查詢結果。此技能適用於 Claude Code、Cursor 或 Codex 等 AI 代理,協助開發者建立穩固且可維護的 Grafana 可觀測性基礎。

相容平台~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 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Grafana 可觀測性

以下是來自生產級自託管堆疊的實務:約 60 個儀表板、400 多條告警規則、50 個抓取任務,以及日誌和追蹤,全部以程式碼管理。每條規則之所以存在,是因為違反它曾導致真實的運維事故。說明了原因,以便你能判斷邊界情況。

首先選擇模式

  • 學習(「教我」、「解釋」、「什麼是」、「考我」):遵循 references/learning-path.md。一次只教一個階段,並在 assets/lab/ 中運行實驗室。確認理解後再繼續。不要一次傾倒所有階段。
  • 建構(儀表板、告警、管線、Terraform 或上線部署):遵循以下工作流程,且只開啟任務所需的參考檔案。
  • 規劃導入(在組織層級):references/implementation-plan.md。

堆疊總覽圖

 應用程式 / 主機 / 網路設備 / 雲端 API
      │ 指標 (exporters, /metrics)     │ 日誌 (檔案, docker, syslog)   │ 追蹤 (OTLP)
      ▼                                   ▼                                ▼
  Prometheus  ◄── 抓取 ──        Grafana Alloy (收集器:探索、重新標籤、遮罩、轉發)
      │                                   │                                │
      │                                 Loki                             Tempo
      └──────────────┬────────────────────┴────────────────────────────────┘
                     ▼
                 Grafana  ── 儀表板、Explore、告警 ──► 聯絡點 (聊天、電子郵件、on-call)
                     ▲
                 Terraform (資料夾、資料來源、規則、路由) + 腳本 (儀表板) + git

詳細資訊:references/architecture.md

硬性規則

  1. 程式碼是唯一的真相來源。 透過 Terraform 變更告警,並透過產生器腳本或存放在 git 中的 JSON 來建構儀表板。UI 中的點擊在下一次 apply 時會遺失,或者更糟,下一次 apply 會默默地還原它。
  2. 在任何 apply 之前,檢查兩種漂移。 (a) 存在於運行中但不在程式碼中的規則:未經目標的 apply 會刪除它們。(b) 存在於程式碼中但已在運行中被修改的規則:apply 會還原它們。「沒有變更」的計畫並不能證明 Terraform 從未見過的規則沒有問題。請參閱 references/as-code.md。
  3. 保護已儲存的計畫。 執行 terraform plan -out,然後拒絕任何你沒有意圖的 delete/replace 作業,無論資源為何。在資料夾上設定 prevent_destroy。刪除 Grafana 資料夾會刪除其中的所有儀表板和規則。
  4. 使用服務帳號 Token,絕不使用 admin:password。 如果狀態是在 Token 認證下建立的,那麼使用基本認證的 apply 會計畫刪除並重建資料夾、聯絡點和政策樹。這曾經在一次 apply 中清除了 59 個儀表板和整個路由樹。
  5. 絕不將 notification_settings(聯絡點)放在規則上。 包含此設定的規則會完全跳過政策樹。它會繞過嚴重性路由、重複間隔和靜音時間。在一個環境中,217 條規則中有 196 條這樣做,而沒有人注意到。
  6. 將閾值放在 Grafana 的 threshold 階段中,而不是 PromQL 內部。 使用 expr > 90 時,健康的主機不會回傳任何序列,Grafana 將其解讀為 NoData,而不是 OK。查詢原始值;在階段 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 回應不會告訴你實際寫入了什麼內容。兩個人或兩個 session 之間的協議不是驗證;一個命令才是。

任何變更的工作流程

  1. 說明面板或告警回答的問題,以及誰會根據它採取行動。如果沒有人會對某個告警採取行動,那就是儀表板面板,而不是告警。
  2. 在 Explore 或透過資料來源代理 API 驗證查詢。 檢查它是否回傳資料、你將用於分組或路由的標籤是否正確,以及在健康時的行為(空?零?)。
  3. 以程式碼撰寫:Terraform 規則群組、儀表板產生器或 Alloy 設定。遵循 references/alerting.md 或 references/dashboards.md。
  4. 檢查漂移,然後執行 terraform plan -out=tfplan。閱讀每個折疊的 ~ 區塊,特別是在 grafana_notification_policy 上,因為它決定所有告警的去向。
  5. 使用服務帳號 Token 執行已儲存的計畫。 在不確定時使用 -target。
  6. 從 API 讀回設定,確認規則已評估(狀態不是 Error/NoData),對於告警,端到端觸發測試通知到真實的聯絡點。
  7. 提交並附上原因。在程式碼中留下註解,說明為何某個選擇看似錯誤但其實是刻意的。

完成定義

告警規則:在 Terraform 中;設定了 severity 標籤;摘要和描述模板包含受影響的主機或服務以及當前值;刻意選擇了 no_data_state;for 足夠長以避免抖動;透過樹路由(沒有每個規則的聯絡點);描述中包含操作手冊連結或第一步驟;經過端到端測試;它不會與現有規則重複分頁。

儀表板:在 git 中(產生的,或已匯出並移除 id/version 的);位於正確的資料夾中;從總攬樞紐連結並可返回;為環境/主機設定變數;每個面板都有一個提出或回答問題的標題;已設定單位和閾值;連結上設定了 keepTime。

新的匯出器或資料來源:使用穩定的標籤進行抓取(env、team、service、role);由全域的 up == 0 規則涵蓋(不要新增單獨的規則);如果它有最後運行時間或新鮮度指標,則需要一個陳舊性規則;已新增到元監控審計;資料來源具有固定的 uid。

參考索引

檔案何時開啟
learning-path.md教學或學習時,階段式進行並搭配實驗室
architecture.md選擇元件、標籤、保留、認證、高可用性時
queries.md撰寫 PromQL 或 LogQL,或查詢看起來有問題時
dashboards.md建構或審查儀表板時
alerting.md規則、路由、聯絡點、靜音、疲勞管理時
as-code.mdTerraform、API、備份、漂移、復原時
meta-monitoring.md證明監控系統本身正常運作時
implementation-plan.md向團隊或公司導入 Grafana 時

資產:assets/lab/ 是一個本機 Docker Compose 實驗室。 assets/terraform-starter/ 是一個入門的 Terraform 堆疊,已預先接上安全預設值。

相關技能