evlog enrichers实战：自动为每条事件附加User-Agent、地理位置与trace上下文

【免费下载链接】evlogDigging through logs is not observability. Its hope — wide events, structured errors, TypeScript-first, every runtime.项目地址https://gitcode.com/gh_mirrors/ev/evlog点击查看免费下载evlog 的 **enrichers日志增强器**让每条宽事件wide event在打印前自动带上User-Agent、地理位置和 trace 上下文全程无需改动业务代码——这正是它区别于只会打印字符串的日志库的地方。一、enricher 在日志流水线中的位置evlog 的事件生命周期是这样的log.info(...) → enricher 增强 → 打印到控制台 → 推送到下游drainenricher 是一条横切的增强管道它运行在事件发出之后、打印和推送之前。这意味着你不需要在每个log.info()调用点手动塞字段增强后的事件会同时出现在控制台输出和所有下游存储中增强逻辑与业务代码完全解耦换框架也不用重写。官方文档对这一机制的完整说明见 enrichers 使用文档。二、快速上手一行代码启用全部内置增强器evlog 内置了四个开箱即用的增强器并且提供了createDefaultEnrichers()组合函数按userAgent → geo → requestSize → traceContext的顺序一次接齐组合逻辑见 createDefaultEnrichers 源码import { createDefaultEnrichers } from evlog/enrichers const enrich createDefaultEnrichers() // 以 Express 为例其他框架只需替换这一行的接线方式 app.use(evlog({ enrich }))不同框架只改接线这一步Nitro/Nuxt 通过evlog:enrich钩子挂载SvelteKit 传给createEvlogHooks({ enrich })独立运行则用enricherPlugin挂到initLogger的插件列表里。四个增强器本身的代码在所有框架中完全一致。三、四个内置增强器逐个看1. User-Agent 解析自动识别浏览器、系统与设备createUserAgentEnricher()从User-Agent请求头解析出结构化的 UserAgentInfo 并写入event.userAgent字段内容browserEdge、Chrome、Firefox、Safari 及版本号osWindows、macOS、iOS、Android、Linuxdevicemobile/tablet/desktop/bot/unknown几个工程细节值得留意解析逻辑源码Edge 先于 Chrome 匹配避免 Edge 被误判成 Chrome含bot/crawl/spider等特征的请求会被标记为bot方便你单独统计爬虫流量请求头缺失时整个字段直接跳过不会写入垃圾数据。解析效果示意{ userAgent: { browser: { name: Chrome, version: 120.0.0.0 }, os: { name: macOS, version: 10.15.7 }, device: { type: desktop } } }2. 地理位置从 Vercel 与 Cloudflare 头部自动提取 createGeoEnricher()把平台注入的地理信息提取到event.geocountry、region、city、latitude、longitude等类型定义见 GeoInfo。它不需要你调用任何 IP 定位 API只读平台已经算好的头部部署平台读取的头部覆盖度Vercelx-vercel-ip-country等全套国家/地区/城市/经纬度Cloudflarecf-ipcountry仅国家码⚠️Cloudflare 注意city、latitude等字段在 Cloudflare 上是request.cf对象的属性并不以 HTTP 头部形式存在。需要完整地理数据时写一个读取request.cf的自定义增强器即可见下文。3. 请求体大小量化每条事件的体量createRequestSizeEnricher()从请求和响应的Content-Length头部取值写入event.requestSize { requestBytes, responseBytes }。排查哪类请求传了大 payload时特别有用。分块传输chunked没有Content-Length对应字段保持为空属正常现象。4. Trace 上下文W3C traceparent 一键解析 createTraceContextEnricher()解析 W3C Trace Context 规范的traceparent/tracestate头部格式为{version}-{traceId}-{spanId}-{flags}写入三处event.traceContext完整的原始值 解析结果event.traceId顶层 32 位 trace ID方便直接按字段检索event.parentSpanId调用方caller的 span ID。一个容易踩的坑trace 增强器源码入站traceparent里的 spanId 属于发起调用的上游服务所以 evlog 把它记为parentSpanId而不动event.spanId——当前服务的 spanId 应交由你的 instrumentation如 OpenTelemetry 的getActiveSpan()写入。这样日志、链路追踪系统就能用同一个traceId对上。四、省心又安全覆盖策略、错误隔离与敏感头过滤内置增强器敢默认开启靠的是三条安全设计overwrite默认false如果你手动通过log.set()设置过geo等字段增强器不会覆盖你的值错误隔离每个增强器都基于 defineEnricher 工厂 构建compute抛错只会被记录为[evlog/name]日志绝不会中断日志管道敏感头自动过滤authorization、cookie、x-api-key等敏感头部在进入 enricher 前就被剔除安全边界由框架层兜底。五、自定义 enricher快速补充部署与租户字段内置的不够用用evlog/toolkit的defineEnricher十行以内就能加一个自己的所有样板错误隔离、undefined 跳过、字段合并都由工厂代劳import { defineEnricher } from evlog/toolkit const deployment defineEnricher({ name: deployment, field: deploymentId, compute: () process.env.DEPLOYMENT_ID, })自定义增强器和内置增强器可以自由组合composeEnrichers典型场景多租户系统的tenant.id、灰度开关featureFlags、按durationMs打标的性能分级等。完整示例见 自定义 Enrichers 文档。六、延伸阅读 evlog 的 enrichers 属于宽事件 结构化思路的一部分事件字段越宽查询维度越多而 enricher 正是以最小成本把事件变宽的标准手段。内置增强器全集与框架接线示例enrichers 官方文档从零写一个增强器Custom Enrichers 文档全部内置增强器实现packages/evlog/src/enrichers/index.ts赞分享【免费下载链接】evlogDigging through logs is not observability. Its hope — wide events, structured errors, TypeScript-first, every runtime.项目地址https://gitcode.com/gh_mirrors/ev/evlog点击查看免费下载相关推荐developer-roadmap 中的 AI Agent 上下文工程为提示词提供附加上下文Provide Additional Context实战指南developer roadmap 中的 AI Agent 上下文工程为提示词提供附加上下文Provide Additional Context实战指南文档教程知识库用 Airi 仓库的 upload-github-attachment 技能将本地文件上传为 GitHub user-attachments 附件用 Airi 仓库的 upload github attachment 技能将本地文件上传为 GitHub user attachments 附件 在 AiriAI 应用人工智能大模型数字人AI Agent语音前端后端桌面应用移动开发即时通讯3D渲染ChatDev 附件与工件 API 实战指南文件上传、实时事件与打包下载ChatDev 附件与工件 API 实战指南文件上传、实时事件与打包下载 导读 本文以 ChatDev 2.0LLM 驱动的多 Agent 协作平台中的AI AgentAgent 框架Agent 工作流低代码工作流自动化OpenBMB创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考