公開用投影片 1:如何保留可用於障礙調查的 API 日誌

這篇文章適合這樣的人

  • 想重新檢視 API 日誌,但不確定該保留什麼的人
  • 雖然 CloudWatch Logs 裡有日誌,但覺得很難找到調查所需紀錄的人
  • 想整理日誌等級、JSON 格式,以及日誌函式庫角色的人

這篇文章可以學到的內容

  • 從「之後想查什麼」出發,決定要在日誌中留下哪些欄位的思考方式
  • 日誌等級,以及多行、單行、JSON 的使用分工
  • 如何以 requestId 為線索,使用 CloudWatch Logs Insights 搜尋同一次請求的日誌

前言

在重新檢視 API 日誌的過程中,我開始覺得,不只是要把日誌輸出出來,還需要先思考之後要用什麼線索來查。

即使留下了「處理失敗」這種訊息,如果無法知道當時並行執行的是哪一個請求失敗了,就會從尋找調查所需紀錄這一步開始吃力。反過來說,如果為了增加資訊量而把輸入內容或例外全部輸出,又可能連調查其實不需要的個人資料或認證資訊都一起留下。

這篇文章會以一般化的範例,整理 API 日誌的設計與搜尋方式。希望讀者帶走的是,先思考之後要用什麼線索來查,再決定要在日誌中留下哪些欄位 的想法。這次會以 requestId 作為具體例子。

公開用投影片 2:這篇文章希望你帶走的重點

文章流程

公開用投影片 3:文章流程

我們會先看 API 日誌的角色與課題,再整理輸出欄位、等級、格式與函式庫選擇,最後介紹用 Logs Insights 搜尋的範例。

API 日誌的角色

這裡所說的 API 日誌,是指 API 伺服器內的應用程式所留下的紀錄。像是請求開始、處理完成、外部 API 呼叫失敗等,都會記錄下來。

收集、保存與搜尋之間的關係如下。

公開用投影片 4:API 日誌是在處理途中留下的紀錄

使用者操作
    ↓
API 伺服器輸出日誌
    ↓  透過 log driver 等方式收集/轉送
保存到 CloudWatch Logs
    ↓
使用 CloudWatch Logs Insights 搜尋

如果要調查的是 API 抵達之前的通訊障礙,或是負載平衡器、資料庫內部狀態,就還需要各自的日誌或指標。這篇文章只聚焦在調查 API 內部所記錄的處理。

辨識同一請求的欄位

公開用投影片 5:即使有 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 與輸出欄位

公開用投影片 6:透過共通 API 統一 API 日誌輸出

如果各個處理流程各自自由輸出日誌,欄位名稱、格式與例外處理就會變得不一致。因此,可以建立一個共通的日誌 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 可能不足以支援調查,實務上應該要再檢討需要哪些分類。

同時也要決定哪些欄位可以輸出,以及這些值要怎麼處理。例如,應避免不慎記錄以下資訊。

  • 密碼、驗證權杖
  • 電子郵件地址、請求的輸入本文
  • 未經安全確認的例外原文或 SQL

建立共通入口後,可以把這些規則的實作與檢查集中在同一處。除了呼叫端傳入的值之外,也需要確認外部函式庫是否會從其他路徑輸出日誌。測試時應使用明確的假資料,除了確認該出現的欄位有出現,也要確認禁止的值不會被輸出。

日誌等級的使用分工

外部 API 呼叫失敗了一次,但可以透過重試繼續處理。這種情況下,該記錄成 warn、error 還是 fatal 呢?

公開用投影片 7:統一重要性與輸出範圍

除了日誌欄位之外,也要統一記錄時使用的等級。以下是分工的一個範例。

※ 日誌等級的名稱與層級會因函式庫而異。

等級 判斷範例
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 不代表程式會自動結束;停止與結束碼的設定仍需由應用程式端處理。

多行、單行、JSON 的角色

公開用投影片 8:整理 API 日誌,將要搜尋的值分開

例外的堆疊追蹤如果用多行表示,會比較容易讓人閱讀。

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 與函式庫選擇

公開用投影片 9:選擇 API 日誌 Pino 時的判斷軸

Hono 的預設 logger 可以記錄 HTTP 方法、路徑、狀態與處理時間,而且輸出函式也能自訂。 Hono Logger Middleware

API 伺服器除了 HTTP 存取之外,也可能有業務處理或 WebSocket 事件等。若希望這些處理也都能以共通欄位、ID 與例外轉換規則記錄,那就需要從整個應用程式的角度來設計日誌。使用 Pino 並由各處理流程呼叫共通 API,是其中一種做法。

如果要比較函式庫,可以先確認是否符合需求,再從以下觀點縮小候選項目。

函式庫 比較重點
Pino 所需的 JSON 輸出、與既有架構的組合性、實際運作經驗
LogTape TypeScript 的易用性、所需功能、維護持續性
Winston 豐富功能與擴充性,這次實際需要到什麼程度
tslog 所需功能、整合實作成本、實際運作經驗

例如,如果 Pino 與 LogTape 都能滿足需求,那也可以基於實際運作經驗與維護持續性來選擇 Pino。這只是一般化的選型範例,並不代表某個函式庫比較好,也不表示有實測效能結果。

用 Logs Insights 找出同一次請求

現在就用前面決定好的欄位來搜尋日誌。

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 上實際執行得到的結果。

公開用投影片 10:用 ID 篩選同一個 API 處理的紀錄

時間 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 價格

之後想查的內容與日誌欄位

公開用投影片 11:如何保留可用於障礙調查的 API 日誌(總結)

這次我們以「尋找同一個 HTTP 請求的紀錄」為目的,介紹了把 requestId 放進日誌欄位的做法。

為了做到這件事,需要把同一個 ID 傳遞到相關日誌中、統一要留下的內容與等級,並以可搜尋的格式保存。當你把輸出後的日誌再拿去 Logs Insights 篩選一次,就能確認調查所需的欄位是否足夠。

你自己負責的 API,下一個想調查的是什麼呢?請試著看看現在的日誌裡,有沒有留下你想要的那個線索。

參考資料

公開用投影片 12:進一步研究 API 日誌設計


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


精選技術文章翻譯,幫助開發者持續吸收新知。

共有 0 則留言


精選技術文章翻譯,幫助開發者持續吸收新知。
🏆 本月排行榜
🥇
boluoji
📝39   💬3   ❤️7
961
🥈
我愛JS
📝3   💬1   ❤️5
106
🥉
站長阿川
📝1   💬3   ❤️2
44
評分標準:發文×10 + 留言×3 + 獲讚×5 + 點讚×1 + 瀏覽數÷10
本數據每小時更新一次
📢 贊助商廣告 · 我要刊登