Repository navigation
feat(obs): production 結構化 JSON log + HTTP access log 與 request_id - #54
Merged
Merged
Conversation
先前 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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
問題
兩個獨立但相關的觀測性缺口:
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。RequestLoggermiddleware:產生或沿用X-Request-Id、寫回應標頭,記錄method/path/status/duration_ms/client_ip/bytes。error、4xx→warn、其餘info。/healthz不記——容器健康檢查每幾秒一次,記下來只會把有價值的請求洗掉(但仍回傳 request id)。Recovery外層,確保 panic 轉成的 500 仍留下紀錄;這點有專門測試鎖住。.env.example補上LOG_LEVEL與APP_ENV的說明。./cmd/server/,否則新增的測試不會被執行。驗證
實跑(對本機 docker Postgres/Redis 起服務,非只跑測試):
逐項確認:
/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