在 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中文网其他相关文章！