在 LogTape .0 中引入隱式上下文

我很高興地宣布LogTape 0.7.0 的發布，它引入了隱式上下文，這是一項強大的新功能，可以比以往更輕鬆地在整個日誌中新增上下文資訊。整個應用程式。

什麼是隱式上下文？

想像一下您正在應用程式中處理 HTTP 請求。您希望請求處理期間產生的每個日誌訊息都包含請求 ID，無論日誌是在程式碼庫中的哪個位置建立的。在隱式上下文之前，您需要：

1. 透過每個函數呼叫傳遞請求ID
2. 為每個模組建立一個包含上下文的新記錄器
3. 或使用全域變數（這也有自己的問題）

使用隱式上下文，您現在可以在請求處理程序的開頭設定上下文，並且該執行上下文中的每個日誌訊息將自動包含該資訊。這是一個簡單的例子：

function handleRequest(requestId: string) {
  withContext({ requestId }, () => {
    // Any log message in this function or any function it calls
    // will automatically include the requestId
    processRequest();
  });
}

function processRequest() {
  // Note that we don't need to pass the requestId explicitly
  getLogger("processor").info(
    "Processing request: {requestId}"
  );
}

它是如何運作的？

隱式上下文使用底層運行時的上下文本機儲存機制（如 Node.js 的 AsyncLocalStorage）來在程式碼執行過程中維護上下文資訊。這意味著即使跨非同步操作，上下文也能正確維護。

要在應用程式中啟用隱式上下文，您需要使用上下文本地儲存來設定 LogTape：

import { AsyncLocalStorage } from "node:async_hooks";
import { configure } from "@logtape/logtape";

await configure({
  // ... other settings ...
  contextLocalStorage: new AsyncLocalStorage(),
});

嵌套上下文和優先權

隱式上下文的強大功能之一是它們可以嵌套。當您嵌套上下文時，內部上下文會繼承並可以覆寫外部上下文的值：

function handleRequest(requestId: string) {
  withContext({ requestId, stage: "request" }, () => {
    // stage is "request" here
    processUser(1234);
  });
}

function processUser(userId: number) {
  withContext({ userId, stage: "user" }, () => {
    // stage is "user" here, but requestId is still available
    getLogger("processor").info(
      "Processing user: {userId} for request: {requestId}"
    );
  });
}

在解析上下文值時，LogTape 遵循明確的優先順序：

1. 日誌訊息中的明確屬性具有最高優先權
2. 透過 Logger.with() 設定明確上下文具有第二優先級
3. 透過 withContext() 設定的隱式上下文優先權最低

運行時支援

截至 2024 年 10 月，以下位置支援隱式上下文：

• Node.js
• 德諾
• 包子

Web 瀏覽器尚未支援隱式上下文，因為它們正在等待 TC39 非同步上下文提案的實施。

使用案例

隱式上下文對於以下方面特別有價值：

1. 請求追蹤：將請求 ID、使用者 ID 或會話 ID 新增至請求內的所有日誌
2. 事務監控：跨多個操作追蹤事務ID
3. 錯誤上下文：確保錯誤日誌始終具有相關的上下文資訊
4. 效能監控：跨多個操作新增計時資訊
5. 租用戶上下文：在多租用戶應用程式中，追蹤所有操作的租用戶資訊

最佳實踐

使用隱式情境時，請考慮以下最佳實務：

1. 使用隱式上下文來取得真正屬於整個執行上下文的資訊
2. 保持上下文資料輕量－記住它是在整個執行過程中進行的
3. 在您的應用程式中使用有意義、一致的鍵名
4. 考慮使用 TypeScript 來確保上下文結構的一致性
5. 記錄您的應用程式的預期上下文結構

遷移指南

如果您已經在使用 LogTape，升級以使用隱式上下文非常簡單：

1. 更新至 LogTape 0.7.0
2. 將上下文本地儲存加入到您的 LogTape 配置
3. 辨識手動傳遞上下文的位置
4. 在適當的邊界處替換為 withContext() 呼叫

結論

LogTape 0.7.0 中的隱式上下文提供了一種強大的方法，可以將上下文資訊新增到日誌中，而不會弄亂您的程式碼或透過呼叫堆疊手動傳遞上下文。它們在 Web 服務、API 和其他應用程式中特別有價值，在這些應用程式中，跨操作追蹤上下文非常重要。

我很高興看到您將如何使用此功能來改進應用程式的日誌記錄和可觀察性。嘗試一下，讓我知道你的想法！

有關更多信息，請查看有關隱式上下文的完整文件。

以上是在 LogTape .0 中引入隱式上下文的詳細內容。更多資訊請關注PHP中文網其他相關文章！