Cloud Logging 與 Error Reporting

Cloud Logging 與 Error Reporting 簡介

可觀測性 (Observability) 是 Google Cloud Professional Cloud Developer (PCD) 考試的核心支柱。Cloud Logging 是一個全代管服務，可從 Google Cloud、Anthos、AWS、地端伺服器以及任意應用程式程式碼擷取、儲存、搜尋、分析並匯出日誌項目。Error Reporting 建構於 Cloud Logging 之上，會自動彙整並分組執行中應用程式的當機與例外狀況，並在偵測到全新的錯誤特徵 (signature) 時發送通知。

PCD 考試不只考你這些服務「做什麼」，更要求你理解生產環境部署時必須調整的細節：jsonPayload 中哪些 key 是特殊保留、API 接受哪些嚴重性字串、_Default 與 _Required log bucket 差在哪、何時該匯到 BigQuery 而不是 Pub/Sub、Error Reporting 如何分組 stack trace、以及如何透過排除過濾器與短保留期限 bucket 來控制成本。

Cloud Logging 以擷取量 (每 GiB 美金) 與超出免費保留期限後的儲存量計費，所以本章節中的每個架構決策同時也是一個成本決策。Error Reporting 的分析層本身免費 — 但前提是它讀取的底層日誌項目仍然在 _Default 保留期限內。

使用 jsonPayload 進行結構化日誌

純文字日誌 (textPayload 欄位) 雖然可搜尋，但對篩選極為不友善。結構化日誌 (Structured Logging) 會送出一個 JSON 物件，Cloud Logging 會將其解析至 jsonPayload 欄位，之後即可使用 Logging Query Language (LQL) 查詢。

特殊的 jsonPayload key

當 Ops Agent 或 runtime 偵測到下列保留 key 時，Cloud Logging 會將它們提升為 LogEntry 頂層欄位。請務必記熟，情境題常考：

• severity → 提升為 LogEntry.severity
• message → 作為 Logs Explorer 中的標題
• httpRequest → 提升為 LogEntry.httpRequest（狀態碼、延遲、userAgent）
• logging.googleapis.com/trace → 將項目連結到 Cloud Trace span
• logging.googleapis.com/spanId → 綁定到特定 span
• logging.googleapis.com/trace_sampled → 取樣決策的 boolean
• logging.googleapis.com/labels → 使用者自訂 labels
• logging.googleapis.com/insertId → 重試時強制冪等

從應用程式撰寫結構化日誌

在 Cloud Run、App Engine、Cloud Functions 以及搭載 Ops Agent 或 Logging Agent 的 GKE 上，任何你輸出到 stdout/stderr 的單行 JSON 物件都會被自動解析。不需要任何 SDK — print(json.dumps({...})) 就足夠。如果你需要批次處理、重試以及明確的 resource 歸屬，則改用 google-cloud-logging 用戶端函式庫，透過 entries.write REST 方法寫入。

嚴重性層級與篩選

Cloud Logging 僅接受 9 種嚴重性數值，定義於 google.logging.type.LogSeverity：DEFAULT、DEBUG、INFO、NOTICE、WARNING、ERROR、CRITICAL、ALERT、EMERGENCY。其他值都會被強制歸類為 DEFAULT。

各語言慣例對應 GCP 嚴重性

• Python logging.INFO → INFO；logging.ERROR → ERROR；logging.CRITICAL → CRITICAL
• Java java.util.logging.Level.WARNING → WARNING；SEVERE → ERROR
• Node.js console.error → ERROR；console.warn → WARNING；console.log → INFO
• Go log.Fatal 退出前會寫入一筆 CRITICAL 項目

LQL 篩選與嚴重性階梯

LQL 嚴重性篩選包含所有更高層級。severity >= WARNING 會回傳 WARNING、ERROR、CRITICAL、ALERT 與 EMERGENCY — 非常適合用於「比門檻更嚴重就觸發」的警示政策。可與 resource 篩選結合：

resource.type="cloud_run_revision"
resource.labels.service_name="checkout-api"
severity >= ERROR

用 logging.googleapis.com/trace 進行 Trace 關聯

在 Google Cloud 上最實用的可觀測性技巧，就是把一筆日誌與產生它的完整分散式 trace 對應起來。Cloud Run、App Engine 與 Cloud Functions 會自動把 trace context 注入 X-Cloud-Trace-Context HTTP 標頭。

Trace key 格式

把 logging.googleapis.com/trace 設為完整的 resource name：projects/PROJECT_ID/traces/TRACE_ID。只填 TRACE_ID 無法在 Logs Explorer 側邊欄正確連結。Agent 與大多數用戶端函式庫只要你提供 trace_id 就會自動組裝完整路徑。

搭配 spanId

加上 logging.googleapis.com/spanId（16 字元的 hex 字串）可把項目錨定到 trace 內的特定 span，這樣 Trace UI 才能正確呈現「此 span 的日誌」，而不會混入同一請求中其他 RPC 的日誌。對於以 OpenTelemetry 進行測量的應用，Cloud Logging 的 OTel exporter 會自動填入這兩個欄位。

Propagation 規則

• Inbound：讀取 X-Cloud-Trace-Context（TRACE_ID/SPAN_ID;o=TRACE_TRUE）
• Outbound：呼叫下游服務時轉發同一個標頭
• gRPC：使用 grpc-trace-bin binary metadata 或 W3C traceparent 標頭

Log Buckets：_Default、_Required 與自訂

每個 Google Cloud 專案都有兩個無法刪除的系統 bucket：_Required 與 _Default。每個專案最多可額外建立 100 個 log bucket，以套用精細的保留期限與 CMEK 政策。

_Required bucket

收納 Admin Activity 稽核日誌、System Event 稽核日誌與 Access Transparency 日誌。保留期限固定為 400 天，無法調整、無法匯出、無法停用。_Required 的儲存完全免費。

_Default bucket

收納所有沒有被 disabled=false 路由 sink 攔截的其餘日誌。預設保留期限 30 天，可調整為 1 天到 3650 天 (10 年)。Data Access 稽核日誌會落在這裡，除非你顯式啟用並改路由它處。

自訂 bucket

使用 gcloud logging buckets create LOG_BUCKET_NAME --location=LOCATION --retention-days=DAYS 建立。自訂 bucket 可：

• 透過 --cmek-kms-key-name 套用 CMEK
• 選擇特定區域（資料主權）
• 每個 bucket 獨立設定 1 至 3650 天的保留期限
• 透過 --enable-analytics 啟用 Log Analytics（BigQuery 後端查詢）

Log Sinks：路由至 BigQuery、GCS、Pub/Sub 與 Splunk

Sink 是定義在專案、folder、billing-account 或組織層級的路由規則。每筆比對到的日誌項目都會被遞送至 sink 的目的地，與原始 bucket 並存（或在搭配 exclusion 時改為取代）。

Sink 目的地

• Cloud Logging bucket（同專案或跨專案）：典型的「把安全日誌集中送到中央專案」模式
• BigQuery dataset：臨時 SQL 分析；自動建立帶 _YYYYMMDD 切分的 table 或 partitioned table（建議用後者）
• Cloud Storage bucket：長期封存；以 LOG_NAME/YYYY/MM/DD/HH00/ 前綴每小時批次寫入檔案
• Pub/Sub topic：透過 Dataflow Pub/Sub to Splunk 範本即時串流到 Splunk、其他 SIEM 或自訂消費者

Writer identity

每個 sink 會建立一個 writer identity 服務帳號，名稱為 [email protected]（組織層級 sink 則是專屬的 p-PROJECT_NUMBER-LOCATION@...）。你必須在日誌流通前，授予這個身分目的地的寫入權限 — roles/bigquery.dataEditor、roles/storage.objectCreator 或 roles/pubsub.publisher。

Aggregated sinks

在 folder 或組織層級建立 aggregated sink 並帶 --include-children，它會擷取底下所有專案的日誌，達成「整個組織共用一個中央安全日誌專案」的設計。

Log-based Metrics：Counter 與 Distribution

Log-based metrics 把日誌內容轉換為 Cloud Monitoring 可圖表化與警示的時序資料，共有兩種類型。

Counter metrics

每比對到一筆日誌就加一。系統 metrics 免費，使用者定義的會依 chargeable label 計費。常見用途：

• 「每分鐘有幾筆 500 回應」→ 篩選 httpRequest.status >= 500
• 「登入失敗次數」→ 篩選 jsonPayload.event="login_failed"

建立指令：gcloud logging metrics create LOGIN_FAILURES --description="..." --log-filter='resource.type="cloud_run_revision" AND jsonPayload.event="login_failed"'。

Distribution metrics

從每筆比對項目抽出一個數值，建立 histogram。當你關心百分位數而不只是次數時必須用這種。常見用途：

• 從 httpRequest.latency 取出 p95 請求延遲
• 從 jsonPayload.bytes_processed 取出 payload 大小分布

需指定 --value-extractor（例如 EXTRACT(jsonPayload.latency_ms)）與 bucket 邊界 (linear、exponential 或 explicit)。也可透過 --label-extractor 抽出 labels，用以切分 tenant、區域或 endpoint。

Quota 與注意事項

• 每個專案最多 500 個 log-based metrics
• 每個 metric 最多 10 個使用者定義 labels，每分鐘 30 個 chargeable label values 後會被節流
• 不會回溯：metric 從建立時間之後開始計數，無法追溯歷史

Error Reporting：以 Stack Trace 特徵自動分組

Error Reporting 會從 _Default 與其他仍開啟 ingestion 的自訂 bucket 讀取日誌，然後將共享同一指紋 (fingerprint) 的 stack trace 分組為 error groups。

分組原理

分組器會抽出例外類型與 stack trace 的頂端 frames，並把動態內容 (記憶體位址、vendored code 的行號、匿名 lambda 名稱) 正規化為一個 signature。所有 signature 相同的項目會合併為一筆 ErrorGroup 資源，在 console 中以單一卡片呈現，包含首次發生時間、最近發生時間、總次數與受影響的服務版本。

支援的 runtime

當 stack trace 以平台慣用格式輸出時，自動偵測適用於 Java、Python、Node.js、Go、.NET、Ruby 與 PHP。其他語言則需自行格式化 trace，並把它放在 jsonPayload.message 中，同時加上 @type = type.googleapis.com/google.devtools.clouderrorreporting.v1beta1.ReportedErrorEvent。

通知

每個專案可設定 email 通知，在「首次出現某 signature」與「已解決後又重新發生」時觸發。亦支援透過 Google Cloud Console 行動 App 的 push 推播。與 PagerDuty 或 Slack 的整合是間接達成：對 log-based metric logging.googleapis.com/byte_count 或自訂 metric 建立警示政策，再透過 Notification Channels 路由。

Cloud Logging API：應用程式埋點

對於不在自動測量 runtime 中執行的工作負載（地端伺服器、批次作業、行動端 telemetry），請直接使用 Cloud Logging API。

entries.write

POST https://logging.googleapis.com/v2/entries:write 每次最多接受 1,000 筆項目或 10 MB，以先到者為準。每筆項目必須包含 logName（projects/PROJECT_ID/logs/LOG_ID）、resource（含 type 與 labels），並且只能擇一帶 textPayload、jsonPayload 或 protoPayload。

用戶端函式庫的批次

官方函式庫 (google-cloud-logging for Python、@google-cloud/logging for Node.js、cloud.google.com/go/logging for Go) 包裝了 entries.write，提供：

• 可設定 delay_threshold 與 batch_size 的程序內批次
• 在背景 worker goroutine/thread 上 flush
• 在 Cloud Run、GKE、GCE、App Engine 上自動偵測 resource
• 內建對 UNAVAILABLE 與 DEADLINE_EXCEEDED 的指數回退重試

認證

服務帳號需有 roles/logging.logWriter。在 Cloud Run、App Engine、Cloud Functions、GKE Workload Identity 與 Compute Engine 上，平台預設服務帳號已經帶有此角色（除非你移除）。外部機器則應使用服務帳號金鑰或更佳的 Workload Identity Federation — 絕不要嵌入長效金鑰。

保留期限設定與成本控制

Cloud Logging 成本分兩部分：擷取量（每月每專案前 50 GiB 免費，之後每 GiB 計費）與超出免費保留期限後的儲存量（_Default 含 30 天免費）。

個別 bucket 設定保留期限

gcloud logging buckets update _Default \
  --location=global \
  --retention-days=7

把 _Default 從 30 天降到 7 天完全不影響擷取費用 — 它只影響「超過 30 天後」才開始計算的儲存費用，所以降到 30 天以下根本省不到錢。要省錢，請在擷取前就排除日誌。

鎖定保留期限以符合法規

在 bucket update 時加上 --locked，可讓保留期限變為不可變：包括專案 owner 在內，任何人都無法縮短保留期限，bucket 中所有項目過期前也無法刪除 bucket。此設定可滿足 HIPAA、PCI-DSS 與 SEC 17a-4 的 WORM 法規要求。

Log Bucket 的 CMEK

預設情況下 Cloud Logging 以 Google 代管金鑰加密靜態資料。對於受法規約束的工作負載，請使用 Customer-Managed Encryption Keys (CMEK)，金鑰存於 Cloud KMS。

CMEK 的兩種範圍

1. 專案預設金鑰 — 在專案或 folder 層級用 gcloud logging cmek-settings update --kms-key-name=... 套用。專案內任何新建的 log bucket 都會繼承此金鑰。
2. 個別 bucket 金鑰 — 在 bucket 建立時用 --cmek-kms-key-name 設定。無法對既有 bucket 追加 CMEK；必須新建一個 bucket 並把日誌改路由過去。

IAM 需求

授予 Cloud Logging 服務帳號 roles/cloudkms.cryptoKeyEncrypterDecrypter 在該 KMS 金鑰上的權限。服務帳號名稱為 [email protected]。沒有這個授權時，匯入受 CMEK 保護的 bucket 會靜默失敗，項目會被丟棄。

區域對齊

KMS keyring 必須與 log bucket 在相同區域，或在涵蓋它的 multi-region。us-central1 bucket 無法使用 europe-west1 的金鑰。

排除過濾器

排除過濾器 (Exclusion Filters) 套用於 _Default sink 或任何自訂 sink 上，會在擷取計費前就丟掉比對到的項目。這是 Cloud Logging 成本控制最大的槓桿。

常見排除規則

• 健康檢查探針：httpRequest.requestUrl=~"/healthz$" AND httpRequest.status=200
• 冗長的 Kubernetes 稽核日誌中 RequestReceived 階段：protoPayload.@type="type.googleapis.com/google.cloud.audit.AuditLog" AND protoPayload.metadata.stage="RequestReceived"
• 低於延遲門檻的 Cloud SQL slow-query 成功項目
• 靜態資源 URL 的重複 load balancer 項目

設定排除規則

gcloud logging sinks update _Default \
  --add-exclusion=name=skip-healthz,filter='httpRequest.requestUrl=~"/healthz$"'

每個 sink 最多可掛 50 條排除規則。每條規則可加 disabled 旗標供臨時除錯 — 重現事故時打開取得完整日誌，事後再關回去。

Log Analytics 與 BigQuery 整合

Log Analytics 是 Cloud Logging 的一項功能，可以讓你直接用標準 SQL 查詢 log buckets，無須先匯出至 BigQuery。建立 bucket 時加上 --enable-analytics 啟用，既有 bucket 可升級但此動作不可逆。

用 SQL 查詢 log buckets

啟用 analytics 後，bucket 會被以名為 LOG_BUCKET_NAME._AllLogs 的連結 BigQuery dataset 形式暴露。你可以執行：

SELECT
  timestamp,
  resource.labels.service_name AS service,
  JSON_VALUE(json_payload, '$.user_id') AS user_id,
  severity
FROM `PROJECT_ID.region-LOCATION._AllLogs`
WHERE severity = 'ERROR'
  AND timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)
ORDER BY timestamp DESC
LIMIT 100;

這讓臨時調查不需要再開 BigQuery sink，但不能取代 sink — 當你要把日誌與非日誌 table join 時仍須 sink。長時間 join 事實表 (fact tables) 的場景，使用 partitioned table 的 BigQuery sink 仍是更便宜也更快的選擇。

何時選擇哪條路徑

• 過去 30 天日誌的臨時一次性 SQL → Log Analytics
• 與訂單、客戶或產品 table join → BigQuery sink
• 報表保留期需超過 bucket 保留期限 → BigQuery sink 並以法規期限對齊 partition expiration
• 跨專案集中儀表板 → 組織層級 aggregated sink 寫入單一 BigQuery dataset

稽核日誌分類

PCD 考試要求你熟悉 Google Cloud 的四種稽核日誌類別，全部透過 Cloud Logging 遞送。

Admin Activity

恆久開啟、免費、寫入 _Required 並保留 400 天。記錄每一筆 IAM 變更、資源 create/update/delete 以及設定變更。無法關閉。可用於回答「03:14 是誰改了防火牆規則？」。

Data Access

大多數服務預設關閉（BigQuery DATA_READ 例外，恆久開啟）。分為三個子類型：ADMIN_READ、DATA_READ、DATA_WRITE。可在專案的「IAM 與管理 > 稽核日誌」頁面逐服務啟用，因為對 Cloud Storage 這類高吞吐服務開啟 DATA_READ 會很快吃掉你的擷取帳單。

System Event

恆久開啟、免費，記錄 GCP 自身發起的動作，例如 live migration 或 TLS 憑證自動續發。事故重建時非常有用。

Policy Denied

記錄當 IAM 政策或 VPC Service Controls 規則拒絕請求時的細節。對於「我明明授了權限為什麼這個 service account 還被擋 403？」這類問題不可或缺 — 被拒項目會清楚告訴你是哪條 condition 或 perimeter 擋下了呼叫。

白話文解釋

類比 1：飛機的黑盒子

Cloud Logging 就像客機上的黑盒子。每個感應器讀值、每段駕駛艙廣播、每個狀態旗標都會寫進防竄改的紀錄器。事故調查員到場後，會以毫秒為單位重播這份紀錄。Log buckets 則是你可以選裝的不同黑盒子 — _Required 是法規硬性要求、無法拆除的監管錄音器，_Default 是日常的語音紀錄器，自訂 bucket 則是你在特定艙位 (服務) 加裝、有自己保留規則的額外錄音器。

類比 2：急診室的檢傷分類護士

Error Reporting 就是站在急診室門口的檢傷分類護士。Cloud Logging 是保存每位病患完整病歷的文件倉庫，包含咳嗽和頭痛這種小事。檢傷護士不理日常文書，只標記真正嚴重的個案 — 骨折、胸痛。她也認得回頭客：如果同一位病患帶著相同症狀回來，她不會開新檔案，而是把舊檔翻出來再加一筆。這種指紋比對正是 Error Reporting 對 stack trace 分組的方式，而護士把嚴重個案送進的「快速通道」就是 email/行動 App 通知 on-call 工程師的機制。

類比 3：郵局分揀中心

Log sinks 像郵局的分揀中心。每封信件 (日誌項目) 先送到一條中央輸送帶 (_Default)。分揀台上的規則決定信件下一站該去哪：BigQuery 是想把每封信都建檔好讓 SQL 查詢的研究部門，Cloud Storage 是每週批次收檔的長期典藏庫，Pub/Sub 是把信件即時送到 Splunk 的高速氣壓管道。排除過濾器則是郵局主管直接把垃圾郵件丟進回收桶，避免大家花錢處理它 — 這就是為什麼健康檢查日誌要在擷取前就排除掉。

常見問題

Q1：Cloud Logging 能處理地端伺服器的日誌嗎？

可以。在實體或虛擬伺服器上安裝 Ops Agent（取代舊的 Logging Agent 與 Monitoring Agent 的統一 agent），用服務帳號金鑰或 Workload Identity Federation 設定後，它就會像 GCE VM 一樣把項目串到 Cloud Logging。對於沒有 agent 的自訂應用，直接用 google-cloud-logging 用戶端函式庫呼叫 entries.write REST endpoint 即可。

Q2：Error Reporting 是即時的嗎？

是的，但有一點點擷取延遲。stack trace 落進 _Default 後，Error Reporting 通常會在數秒到一分鐘內偵測並分組。一旦比對到第一筆，新錯誤通知會立刻 email 出去，Google Cloud Console 行動 App 也可推播到手機。

Q3：怎麼為 SOX 合規保留稽核日誌七年？

兩種做法。(1) 不能把 _Required 拉長 — 它固定 400 天。改為在組織層級建立 aggregated sink，篩選 logName:"cloudaudit.googleapis.com"，送到帶有 7 年保留政策與 bucket lock 的 Cloud Storage bucket，或送到 --retention-days=2555 --locked 的 Cloud Logging bucket。(2) 路由到 BigQuery 以利臨時稽核查詢；BigQuery dataset 有自己的保留控制。

Q4：我的 Cloud Logging 帳單被 Kubernetes container 日誌吃光，怎麼辦？

對 _Default 套用排除規則丟掉吵雜 namespace（resource.labels.namespace_name=~"^(kube-system|istio-system)$"），丟掉 sidecar 的冗長 info 日誌，並把稽核日誌階段從 RequestReceived 降到只留 ResponseComplete。如果還是需要這些資料，可送一份取樣 (例如 10%) 的串流到低成本 Cloud Storage sink，其餘完全排除。

Q5：怎麼讓日誌與 trace 並排顯示？

在每筆日誌中注入 logging.googleapis.com/trace = projects/PROJECT_ID/traces/TRACE_ID。在 Cloud Run、App Engine 與 Cloud Functions 上，平台會從請求標頭 X-Cloud-Trace-Context 取出 TRACE_ID — 把它傳到你的結構化日誌 payload，之後在 Logs Explorer 開任一筆項目按「Show in context」，或直接跳到 Trace UI 即可。需要 span 層級對應就再加 logging.googleapis.com/spanId。

Q6：Log-based metrics 會回溯嗎？

不會。Log-based metric 從建立時間才開始記錄，只計算之後寫入的項目。如果你需要分析尚未測量的歷史事件，請用 sink 把日誌路由到 BigQuery，再對歷史 partition 跑 COUNT(*) 查詢。