gcp-monitoring-diagnose

GCP Cloud Monitoring 排查

用 gcloud + Monitoring REST API 對任意 GCP 專案做被動根因排查。

何時用

• 服務出事 / 收到告警通知,要快速定位根因
• 想知道「現在哪些告警正在燒」(GCP 沒有 list-incidents API,本 skill 用重放條件算)
• 下鑽某 pod 的 CPU/記憶體、uptime 失敗、指標斷線

前置

• gcloud 已認證且為個人帳號(修復動作要可追溯)
• 目標 project 具 roles/monitoring.viewer(讀);修復另需寫入權限
• scripts/ 路徑下有 lib.sh、metrics.sh、snapshot.sh、safe-apply.sh

診斷流程

1. 入口判斷

   • 使用者有講症狀 / 指定告警 → 直接針對性下鑽(跳到步驟 3)
   • 沒講原因(預設)→ 先跑告警掃描

2. 告警掃描(預設起點)

   bash scripts/snapshot.sh <project>
   

   會重放所有 enabled 告警(PromQL + threshold 兩種)算出「🔥 正在燒的告警」,並列 uptime 狀態。 threshold 重放會完整套用 policy 的 aggregations,避免累積型指標誤判。

3. 下鑽 root cause:對 firing 的告警,依下表用 metrics.sh 拉證據。

   bash scripts/metrics.sh <project> '<filter>' [minutes]            # 拉 time series
   bash scripts/metrics.sh <project> '<promql>' [minutes] --promql   # PromQL instant
   

4. 報告:輸出根因 + 證據(指標值、告警條件、近期 audit log 誰動過)。查誰改過設定:

   gcloud logging read 'logName="projects/<project>/logs/cloudaudit.googleapis.com%2Factivity" AND protoPayload.serviceName="monitoring.googleapis.com"' --project=<project> --limit=5 --freshness=7d --format="table(timestamp,protoPayload.authenticationInfo.principalEmail,protoPayload.methodName)"
   

5. 修復(可選,需使用者確認):只在白名單內,透過 safe-apply。

   bash scripts/safe-apply.sh "<動作描述>" "<gcloud/kubectl 指令>" "<rollback 指令>"
   

Failure pattern 對照

症狀	下鑽手法
uptime check 失敗	metrics.sh <p> 'metric.type="monitoring.googleapis.com/uptime_check/check_passed"' 看哪個 checker_location 為 false
告警該觸發沒觸發 / 觸發找不到原因	讀該 policy 條件(gcloud alpha monitoring policies list),用 metrics 拉同指標跟閾值比對
pod 燒 CPU	metrics.sh <p> 'metric.type="kubernetes.io/container/cpu/core_usage_time"'
pod 燒記憶體	metrics.sh <p> 'metric.type="kubernetes.io/container/memory/used_bytes"'
CrashLoopBackOff / Pending / 重啟	metrics.sh <p> 'kube_pod_container_status_waiting_reason{...}' --promql;kubectl 看事件
Deployment 副本不足	比對 desired vs ready replica 指標
PVC 使用率高	metrics.sh <p> 'metric.type="kubernetes.io/pod/volume/utilization"'
指標斷線(沒資料)	先確認 filter 正確、再確認 metrics-scope 是否涵蓋來源 project(非「沒資料」就是 scope 錯)
告警通知沒收到	gcloud alpha monitoring channels list 看 channel 是否 enabled

安全修復白名單(只有可逆 / 低風險可做)

✅ Monitoring 設定	✅ GKE 輕量(可逆)	⛔ 絕不碰(只給手動建議)
建/修 uptime check、調告警閾值、啟用停用、補通知管道、snooze、建 dashboard	kubectl rollout restart、kubectl scale --replicas	刪非自建資源、改 IAM、改/刪 PVC/StatefulSet 資料、改 secret、改 image/env/limit、apply 任意 manifest

超出白名單 → 只輸出建議的手動步驟,不執行。

安全約束(務必遵守)

• 修復一律走 safe-apply.sh,不要直接執行變更指令(確保 guard + 留痕 + 確認)。
• 修復前確認 gcloud config get-value account 是個人帳號;safe-apply 會擋 SA。
• 唯讀診斷(snapshot/metrics)可自由執行;變更動作必須先取得使用者確認。
• 透過 safe-apply 包裝破壞性 gcloud 指令(如 delete)時,務必帶 --quiet;否則 gcloud 自己的互動確認會卡住(stdin 已被 safe-apply 的確認消耗),指令以非 0 退出。safe-apply 的確認應是唯一確認點。