用途:为分布式服务提供可观测性,包括请求追踪、结构化日志聚合、操作耗时测量以及后台 worker 的指标收集。
主要能力:使用关联 ID(correlation ID)跨服务追踪请求;输出 JSON 格式日志便于机器解析;通过 contextvars(Python)或 AsyncLocalStorage(TypeScript)在异步调用间传播请求上下文;提供 timed 装饰器测量操作耗时,可设置阈值仅记录慢操作;提供 worker_job_context 上下文管理器记录后台任务开始、完成与失败。
使用方式:Python 侧调用 configure_logging 初始化,用 get_logger 获取带上下文的日志器,通过 set_logging_context 设置请求上下文,用 timed 装饰函数,用 worker_job_context 包裹后台任务。TypeScript 侧使用 createContext、runWithContext、getLogger、timed 以及 Express 中间件 loggingMiddleware。示例中 FastAPI 中间件会读取 X-Correlation-ID 请求头并回写响应头。
适用场景:需要跨服务请求追踪、希望日志可被聚合工具解析、需要测量操作耗时、构建带指标的后台 worker。
限制与注意事项:资料未提供安装命令、依赖版本、平台支持范围或收费信息。最佳实践包括始终使用关联 ID、使用 JSON 格式、通过 contextvars 传播上下文、设置阈值只记录慢操作、绝不记录密码令牌或 PII、开发用 DEBUG 生产用 INFO。常见错误包括缺少关联 ID、日志非结构化、记录敏感数据、无上下文传播、记录过多日志。