
在重新檢視 API 日誌的過程中,我開始覺得,不只是要把日誌輸出出來,還需要先思考之後要用什麼線索來查。
即使留下了「處理失敗」這種訊息,如果無法知道當時並行執行的是哪一個請求失敗了,就會從尋找調查所需紀錄這一步開始吃力。反過來說,如果為了增加資訊量而把輸入內容或例外全部輸出,又可能連調查其實不需要的個人資料或認證資訊都一起留下。
這篇文章會以一般化的範例,整理 API 日誌的設計與搜尋方式。希望讀者帶走的是,先思考之後要用什麼線索來查,再決定要在日誌中留下哪些欄位 的想法。這次會以 requestId 作為具體例子。


我們會先看 API 日誌的角色與課題,再整理輸出欄位、等級、格式與函式庫選擇,最後介紹用 Logs Insights 搜尋的範例。
這裡所說的 API 日誌,是指 API 伺服器內的應用程式所留下的紀錄。像是請求開始、處理完成、外部 API 呼叫失敗等,都會記錄下來。
收集、保存與搜尋之間的關係如下。

使用者操作
↓
API 伺服器輸出日誌
↓ 透過 log driver 等方式收集/轉送
保存到 CloudWatch Logs
↓
使用 CloudWatch Logs Insights 搜尋
如果要調查的是 API 抵達之前的通訊障礙,或是負載平衡器、資料庫內部狀態,就還需要各自的日誌或指標。這篇文章只聚焦在調查 API 內部所記錄的處理。

例如,假設有以下日誌。
10:00:00 處理開始
10:00:01 處理開始
10:00:02 處理失敗
失敗的是最先開始的請求,還是下一個呢?
在這個例子裡,只看時間無法判斷。因此,我們會替每一次 HTTP 請求加上 ID,並在與該請求相關的日誌中留下相同的值。
{"event":"request.started","requestId":"demo-001"}
{"event":"request.started","requestId":"demo-002"}
{"event":"request.failed","requestId":"demo-001","errorCode":"TIMEOUT"}
這樣就能把 demo-001 的開始與失敗連結起來。
| 想查的內容 | 留下的欄位範例 | 角色 |
|---|---|---|
| 什麼時候發生 | 時間 | 確認先後關係 |
| 是什麼處理/事件 | event |
區分開始、完成、失敗等 |
| 是同一次請求嗎 | requestId |
把相關日誌串起來 |
| 是哪一類失敗 | errorCode |
依失敗分類做篩選 |
ID 需要在接收到請求的當下產生或驗證,並傳遞到相關處理流程中記錄。若想調查的是長時間執行的背景工作,或跨多個服務的處理,則要思考適合調查對象的識別子,例如工作 ID 或追蹤 ID,以及它們的傳遞方式。

如果各個處理流程各自自由輸出日誌,欄位名稱、格式與例外處理就會變得不一致。因此,可以建立一個共通的日誌 API,統一輸出的規則。
各處理流程 → 共通日誌 API(appLogger)→ Pino → 單行 JSON
接下來是呼叫端決定要留下哪些欄位的偽程式碼。
// 說明用偽程式碼
// 假設 TimeoutError 是在應用程式端定義的型別
const entry = {
requestId,
event: "request.failed",
errorCode: error instanceof TimeoutError
? "TIMEOUT"
: "UNKNOWN",
}
appLogger.error(entry)
const entry 是組裝要傳給日誌的欄位,appLogger.error(entry) 則是呼叫共通入口。這個例子不會直接複製例外原文,而是依照型別選擇預先定義的分類名稱。TIMEOUT 代表逾時,UNKNOWN 代表在這個簡化範例中無法分類的失敗。
這段程式省略了共通 API 的實作、ID 的產生/驗證,以及例外型別的定義。因為只用 UNKNOWN 可能不足以支援調查,實務上應該要再檢討需要哪些分類。
同時也要決定哪些欄位可以輸出,以及這些值要怎麼處理。例如,應避免不慎記錄以下資訊。
建立共通入口後,可以把這些規則的實作與檢查集中在同一處。除了呼叫端傳入的值之外,也需要確認外部函式庫是否會從其他路徑輸出日誌。測試時應使用明確的假資料,除了確認該出現的欄位有出現,也要確認禁止的值不會被輸出。
外部 API 呼叫失敗了一次,但可以透過重試繼續處理。這種情況下,該記錄成 warn、error 還是 fatal 呢?

除了日誌欄位之外,也要統一記錄時使用的等級。以下是分工的一個範例。
※ 日誌等級的名稱與層級會因函式庫而異。
| 等級 | 判斷範例 |
|---|---|
trace |
更細微的診斷資訊 |
debug |
供調查用的詳細資訊 |
info |
主要成功事件或狀態變更 |
warn |
出現異常,但可透過重試等方式繼續處理 |
error |
被要求的處理失敗 |
fatal |
無法繼續執行,例如啟動失敗 |
例如「外部 API 呼叫失敗一次,但還可以進行重試」這種情況,依照這個規則會記錄成 warn。因為在那個當下,還不知道重試之後是否最終會成功。
info 可以用來記錄像是「錄音開始/結束」或「會議記錄產生完成」這類里程碑。這些資訊能幫助在障礙調查時判斷流程進行到哪一步。
「記錄成哪個等級」和「輸出哪個等級以上的日誌」是不同的設定。舉例來說,若使用 Pino 的預設等級,將最小等級設為 info,那麼會輸出 info、warn、error、fatal。 Pino 的日誌等級設定
import pino from "pino"
const logger = pino({ level: "info" })
不要把所有 HTTP 4xx 一律都當成 error,而是要根據情況判斷它是預期內的輸入錯誤,還是應由維運處理的異常。此外,輸出 fatal 不代表程式會自動結束;停止與結束碼的設定仍需由應用程式端處理。

例外的堆疊追蹤如果用多行表示,會比較容易讓人閱讀。
Error: 處理失敗
at handler (...)
at service (...)
不過,如果收集端是以換行作為事件分隔,這一次錯誤可能會被拆成多個事件。Docker 的 awslogs driver 也可以指定開頭行的模式,將後續行合併成同一個事件。 Docker 的多行日誌設定
如果一筆日誌以單行輸出,即使是逐行收集,也比較容易被視為一個完整事件。再進一步把它轉成 JSON,就能把想搜尋的值獨立成欄位。
{"event":"request.failed","requestId":"demo-001","errorCode":"TIMEOUT"}
| 做法 | 目的 |
|---|---|
| 多行顯示 | 讓人比較容易讀取細節 |
| 一筆一行 | 即使逐行收集,也較容易保留為單一事件 |
| 拆成 JSON 欄位 | 方便用 ID 或失敗分類搜尋 |
上面兩段日誌只是用來說明格式的一般例子,並不表示可以從上方的錯誤訊息直接判定 TIMEOUT。失敗分類仍然是由前面的偽程式碼那樣,由應用程式端決定。
JSON 字串中的換行可以用 \n 表示。你也可以把送出時的格式與顯示時的格式分開,例如送出時為單行、觀看時再顯示成多行。

Hono 的預設 logger 可以記錄 HTTP 方法、路徑、狀態與處理時間,而且輸出函式也能自訂。 Hono Logger Middleware
API 伺服器除了 HTTP 存取之外,也可能有業務處理或 WebSocket 事件等。若希望這些處理也都能以共通欄位、ID 與例外轉換規則記錄,那就需要從整個應用程式的角度來設計日誌。使用 Pino 並由各處理流程呼叫共通 API,是其中一種做法。
如果要比較函式庫,可以先確認是否符合需求,再從以下觀點縮小候選項目。
| 函式庫 | 比較重點 |
|---|---|
| Pino | 所需的 JSON 輸出、與既有架構的組合性、實際運作經驗 |
| LogTape | TypeScript 的易用性、所需功能、維護持續性 |
| Winston | 豐富功能與擴充性,這次實際需要到什麼程度 |
| tslog | 所需功能、整合實作成本、實際運作經驗 |
例如,如果 Pino 與 LogTape 都能滿足需求,那也可以基於實際運作經驗與維護持續性來選擇 Pino。這只是一般化的選型範例,並不代表某個函式庫比較好,也不表示有實測效能結果。
現在就用前面決定好的欄位來搜尋日誌。
CloudWatch Logs Insights 可以偵測 JSON 日誌的欄位並用於查詢。這裡先假設 Standard 類別的 log group 中,JSON 會以單一事件的形式到達,且欄位已被偵測。 JSON 日誌欄位偵測
在 AWS 主控台開啟 CloudWatch 的 Logs Insights,選擇目標 log group 與時間範圍。接著把下面的查詢貼到查詢編輯器中。
fields @timestamp, event, requestId, errorCode
| filter requestId = "demo-001"
| sort @timestamp asc
fields 用來選擇要顯示的欄位filter 用來篩選出 requestId 相同的日誌sort 用來依時間由舊到新排序搜尋結果的示意如下。這是虛構結果,並非在 AWS 上實際執行得到的結果。

| 時間 | event | requestId | errorCode |
|---|---|---|---|
| 10:00:00.000 | request.started | demo-001 | — |
| 10:00:00.120 | request.failed | demo-001 | TIMEOUT |
因為開始與失敗是用同一個 ID 排在一起,所以可以看出該請求是在開始後因逾時而失敗。request.started 與 request.failed 是這個例子中定義的事件名稱。@timestamp 是 CloudWatch 處理的日誌事件時間。 Logs Insights 的查詢語法
在實際運作時,還要確認預期欄位是否有送到、目標期間的日誌是否有保留,以及是否能用必要權限進行搜尋。保留期限與費用則要依所使用的區域、log class、資料量等因素確認。 保留期限設定 · CloudWatch 價格

這次我們以「尋找同一個 HTTP 請求的紀錄」為目的,介紹了把 requestId 放進日誌欄位的做法。
為了做到這件事,需要把同一個 ID 傳遞到相關日誌中、統一要留下的內容與等級,並以可搜尋的格式保存。當你把輸出後的日誌再拿去 Logs Insights 篩選一次,就能確認調查所需的欄位是否足夠。
你自己負責的 API,下一個想調查的是什麼呢?請試著看看現在的日誌裡,有沒有留下你想要的那個線索。

原文出處:https://qiita.com/masashige0904/items/22f2836485ecc25ee527