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
硬性規則
- 程式碼是唯一的真相來源。 透過 Terraform 變更告警,並透過產生器腳本或存放在 git 中的 JSON 來建構儀表板。UI 中的點擊在下一次 apply 時會遺失,或者更糟,下一次 apply 會默默地還原它。
- 在任何 apply 之前,檢查兩種漂移。 (a) 存在於運行中但不在程式碼中的規則:未經目標的 apply 會刪除它們。(b) 存在於程式碼中但已在運行中被修改的規則:apply 會還原它們。「沒有變更」的計畫並不能證明 Terraform 從未見過的規則沒有問題。請參閱 references/as-code.md。
- 保護已儲存的計畫。 執行
terraform plan -out,然後拒絕任何你沒有意圖的delete/replace作業,無論資源為何。在資料夾上設定prevent_destroy。刪除 Grafana 資料夾會刪除其中的所有儀表板和規則。 - 使用服務帳號 Token,絕不使用
admin:password。 如果狀態是在 Token 認證下建立的,那麼使用基本認證的 apply 會計畫刪除並重建資料夾、聯絡點和政策樹。這曾經在一次 apply 中清除了 59 個儀表板和整個路由樹。 - 絕不將
notification_settings(聯絡點)放在規則上。 包含此設定的規則會完全跳過政策樹。它會繞過嚴重性路由、重複間隔和靜音時間。在一個環境中,217 條規則中有 196 條這樣做,而沒有人注意到。 - 將閾值放在 Grafana 的 threshold 階段中,而不是 PromQL 內部。 使用
expr > 90時,健康的主機不會回傳任何序列,Grafana 將其解讀為 NoData,而不是 OK。查詢原始值;在階段 C 中進行比較。 - 根據可行動性路由,並將重複間隔視為真正的槓桿。 使用
severity(critical/warning/info)加上urgency=backlog來處理慢性、已知的問題。大多數告警噪音是對已知事物的重複通知。每天重複 critical 告警,每週重複 warning,而不是每小時。 - 升級應該是一種延遲,而靜音是一種確認。 分頁路由使用約 15 分鐘的
group_wait,因此它只會在告警仍在觸發且未被靜音時才進行分頁。事件類型的規則需要keep_firing_for大於等於等待時間,否則它們會在升級之前就解決。 - 監控監控系統本身。 監控評估失敗、通知傳遞失敗、被抑制(靜音)的告警、過期的匯出器和已停止的備份。一個沉默的告警系統看起來與健康的系統完全一樣。請參閱 references/meta-monitoring.md。
- 驗證,不要信任。 在撰寫每個面板或告警查詢之前,先針對資料來源執行查詢。在任何 API 寫入之後,讀回物件並斷言你的變更存在於其中:POST 回應不會告訴你實際寫入了什麼內容。兩個人或兩個 session 之間的協議不是驗證;一個命令才是。
任何變更的工作流程
- 說明面板或告警回答的問題,以及誰會根據它採取行動。如果沒有人會對某個告警採取行動,那就是儀表板面板,而不是告警。
- 在 Explore 或透過資料來源代理 API 驗證查詢。 檢查它是否回傳資料、你將用於分組或路由的標籤是否正確,以及在健康時的行為(空?零?)。
- 以程式碼撰寫:Terraform 規則群組、儀表板產生器或 Alloy 設定。遵循 references/alerting.md 或 references/dashboards.md。
- 檢查漂移,然後執行
terraform plan -out=tfplan。閱讀每個折疊的~區塊,特別是在grafana_notification_policy上,因為它決定所有告警的去向。 - 使用服務帳號 Token 執行已儲存的計畫。 在不確定時使用
-target。 - 從 API 讀回設定,確認規則已評估(狀態不是 Error/NoData),對於告警,端到端觸發測試通知到真實的聯絡點。
- 提交並附上原因。在程式碼中留下註解,說明為何某個選擇看似錯誤但其實是刻意的。
完成定義
告警規則:在 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.md | Terraform、API、備份、漂移、復原時 |
| meta-monitoring.md | 證明監控系統本身正常運作時 |
| implementation-plan.md | 向團隊或公司導入 Grafana 時 |
資產:assets/lab/ 是一個本機 Docker Compose 實驗室。 assets/terraform-starter/ 是一個入門的 Terraform 堆疊,已預先接上安全預設值。