Skip to content

feat(obs): production 結構化 JSON log + HTTP access log 與 request_id - #54

Merged
thothawei merged 3 commits into
mainfrom
claude/structured-log-request-id
Jul 29, 2026
Merged

thothawei merged 3 commits into
mainfrom
claude/structured-log-request-id

Conversation

@thothawei

Copy link
Copy Markdown
Owner

問題

兩個獨立但相關的觀測性缺口:

1. 結構化日誌在輸出前被攤平

cmd/server/main.go 無條件套用 zerolog.ConsoleWriter,而且在 config.Load() 之前執行,連判斷環境的機會都沒有。zerolog 預設輸出就是 JSON,ConsoleWriter 的作用是把 JSON 解析回來、重排成彩色人類可讀文字——等於把業務層已經寫好的結構化欄位(ride_id、attempt、offered)重新攤平成字串。

上線後日誌平台只能全文比對,無法把 ride_id 當條件查詢。功做了,最後一步丟掉。

2. 完全沒有 HTTP access log

router 走 gin.New()(不含 logger 的建構子),只掛了 Recovery 與 CORS。因此沒有任何請求層紀錄:誰打了哪支 API、回什麼狀態碼、花多久,全部沒有。API 變慢時無法知道是哪支端點慢——連「先量測再優化」的第一步都做不到。

改動

  • newLogger(cfg, out):依 APP_ENV 決定格式,production 走 JSON、其餘走 ConsoleWriter。輸出目標以 io.Writer 傳入而非寫死 os.Stdout,否則測試無法斷言實際格式(第一版測試就是因為這點而在測 zerolog 本身,已修正)。
  • LOG_LEVEL(預設 info):排查時可臨時調 debug 而不必改程式重新部署;無法解析時退回 info 並留下 warn。
  • RequestLogger middleware:產生或沿用 X-Request-Id、寫回應標頭,記錄 method / path / status / duration_ms / client_ip / bytes。
    • 依狀態碼分級:5xx→error、4xx→warn、其餘 info。
    • /healthz 不記——容器健康檢查每幾秒一次,記下來只會把有價值的請求洗掉(但仍回傳 request id)。
    • 掛在 Recovery 外層,確保 panic 轉成的 500 仍留下紀錄;這點有專門測試鎖住。
  • .env.example 補上 LOG_LEVEL 與 APP_ENV 的說明。
  • CI unit test 清單加入 ./cmd/server/,否則新增的測試不會被執行。

驗證

實跑(對本機 docker Postgres/Redis 起服務,非只跑測試):

production:{"level":"info","request_id":"80dc676baf4fb911","method":"GET","path":"/liff/","status":200,"duration_ms":5,"client_ip":"127.0.0.1","bytes":2420,"time":1785297198,"message":"http request"}
local      :2026-07-29T11:51:17+08:00 FTL 資料庫 migration 失敗 error="..."(彩色文字)

逐項確認:/healthz 回 request id 但不寫 access log;上游帶入的 X-Request-Id: from-upstream-999 被沿用;404/401 記為 warn;真實 2xx 的 duration_ms=5(確實在量測,非固定 0)。

測試:./cmd/server/、./internal/middleware/、./internal/config/ 以 CI 相同參數(-timeout 60s)全數通過。

負向斷言有做校準——「/healthz 不寫 log」這條先用一般路徑證明同一條斷言路徑抓得到輸出,並實際把 skip 路徑改錯確認測試會 FAIL,避免路徑寫錯導致永遠 PASS。

已知範圍限制

業務層 33 處 log 仍使用全域 logger,尚未自動帶上 request_id。跨層關聯目前靠既有的 ride_id 業務鍵(多數業務 log 都有帶)。要讓 request_id 貫穿業務層需把 context logger 傳進 service 層,屬於較大的重構,本 PR 不含。

🤖 Generated with Claude Code

thothawei and others added 3 commits July 29, 2026 12:04
先前 main.go 無條件套用 zerolog ConsoleWriter,且在 config.Load() 之前執行,
等於把已經寫好的結構化欄位(ride_id、attempt 等)重新攤平成字串,
上線後日誌平台只能全文比對,無法把 ride_id 當條件查詢。

另外 router 走 gin.New() 但只掛了 Recovery 與 CORS,沒有任何 access log:
API 變慢或回 5xx 時,只剩業務層零星紀錄,無從得知是哪支端點、耗時多久,
連「先量測再優化」的第一步都做不到。

- newLogger 依 APP_ENV 決定輸出格式:production 走 JSON,其餘走 ConsoleWriter。
  輸出目標以 io.Writer 傳入而非寫死 os.Stdout,才能在測試中斷言實際格式。
- 新增 LOG_LEVEL(預設 info),無法解析時退回 info 並留下 warn。
- 新增 RequestLogger middleware:產生/沿用 X-Request-Id、寫回應標頭,
  並記錄 method/path/status/duration_ms/client_ip/bytes。
  依狀態碼分級(5xx→error、4xx→warn、其餘 info),/healthz 不記以免洗掉有效訊息。
  掛在 Recovery 外層,確保 panic 轉成的 500 仍會留下紀錄。

驗證:go build、gofmt 通過;cmd/server 與 internal/middleware 測試全數通過
(含 panic→500、上游 id 沿用、/healthz 跳過的反向校準);
並實跑服務確認 production 輸出 JSON、local 輸出彩色文字、
真實請求記到 duration_ms 且 /healthz 未寫入 access log。

備註:業務層 33 處 log 仍使用全域 logger,尚未自動帶上 request_id,
跨層關聯目前靠既有的 ride_id 業務鍵,留待後續處理。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
- .env.example:新增 LOG_LEVEL 並補述 APP_ENV 對日誌輸出格式的影響,
  維持此檔「每個變數都有用途說明」的既有慣例。
- go-ci.yml:unit test 清單加入 ./cmd/server/。該包新增的 newLogger/setupLogger
  測試原本不在 CI 範圍內,不加會直接失去保護。此包不依賴 Docker,
  以 CI 相同參數(-timeout 60s)實測 1.1 秒通過。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@thothawei
thothawei merged commit 4905ceb into main Jul 29, 2026
1 check passed
@thothawei
thothawei deleted the claude/structured-log-request-id branch July 29, 2026 06:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant