【免费下载链接】evlogDigging through logs is not observability. Its hope — wide events, structured errors, TypeScript-first, every runtime.项目地址https://gitcode.com/gh_mirrors/ev/evlog点击查看免费下载evlog是一款 TypeScript 优先的结构化日志库核心理念是宽事件wide events 结构化错误一个请求只产生一条带完整上下文的日志事件。当内置能力不够用时evlog 提供了统一的扩展工具包evlog/toolkit让你用同样简洁的3步完成三件事自建 drain把日志发往任意后端、写插件挂入日志生命周期、为你的框架编写适配器让不支持的框架也能用 evlog。先搞懂 evlog 的扩展架构evlog 的日志管线是一条流水线每个宽事件依次经过你的业务代码 │ emit ▼ 请求生命周期 → enrich补充字段→ tail sample尾部采样→ drain输出官方文档把扩展方式分成三类正好对应本文的3步你想做什么对应概念参考文档把日志发往没有内置适配器的后端自建drainCustom Drains 文档给每个事件加派生字段、响应生命周期事件写插件Plugins 文档让你的框架/运行时接入 evlog写框架适配器Custom Framework 文档好消息是这三样东西共享同一套工具包drain 和 enricher 本质上都是只选了一个钩子的插件所以学会了其中一件另外两件几乎零成本迁移。第1步自建 drain把宽事件发往任意后端drain是管线末端的一步接收宽事件并把它送到某处——HTTP API、消息队列、数据库、webhook、本地文件。evlog 已内置 Axiom、OTLP、Datadog、Sentry、PostHog、文件系统 等适配器如果你的目标平台不在列表里自己写一个只需两个纯函数。两个工厂函数覆盖所有场景你的目标后端使用HTTP 后端REST、JSON 摄取、厂商/v1/logs端点defineHttpDrain非 HTTP 传输gRPC、厂商 SDK、队列、原始 socketdefineDrain以内部 Loki 为例一个完整可运行的 drain 只有约 25 行import { defineHttpDrain } from evlog/toolkit export function createLokiDrain(overrides?: { url?: string, token?: string }) { return defineHttpDrain{ url: string, token: string }({ name: loki, resolve: () ({ url: overrides?.url ?? process.env.LOKI_URL!, token: overrides?.token ?? process.env.LOKI_TOKEN!, }), encode: (events, config) ({ url: ${config.url}/loki/api/v1/push, headers: { Content-Type: application/json, Authorization: Bearer ${config.token} }, body: JSON.stringify({ streams: events.map(e /* 转成 Loki 格式 */) }), }), }) }你只写两件事resolve()返回配置返回null则 drain 自动变 no-opencode()返回 HTTP 请求负载返回null表示本批跳过。重试默认2次、超时默认5000ms、错误隔离、身份头User-Agent: evlog/version和X-Evlog-Source全部由工厂自动处理不需要手写fetch。⚠️ 生产环境记得用createDrainPipeline包一层获得批量发送、失败重试和缓冲区保护——官方建议生产环境永远走 pipeline。第2步写一个插件挂入日志生命周期的任意环节当你要多件事一起干时比如每个事件加字段 事件发出时上报指标 按结果决定是否保留用definePlugin——evlog 的正规扩展点一个对象可以同时订阅多个生命周期钩子并共享状态import { definePlugin } from evlog export const tenantPlugin definePlugin({ name: tenant, onRequestStart({ logger, headers }) { const tenantId headers?.[x-tenant-id] if (tenantId) logger.set({ tenant: { id: tenantId } }) }, enrich({ event }) { event.region process.env.REGION }, })可用的钩子都是可选的按需取用钩子触发时机典型用途setup(ctx)注册时一次读取env、初始化共享状态onRequestStart(ctx)每个请求开始从请求头提取值写入 loggerenrich(ctx)每个事件发出前加派生字段地域、部署 IDkeep(ctx)尾部采样决策按结果强制保留status 400等drain(ctx)每个已发事件副作用告警、镜像到队列onRequestFinish(ctx)响应之后每请求的后处理extendLogger(logger)每个请求给 logger 增加自定义方法几个新手容易踩的坑钩子内部不要抛错保持防御式写法插件按name去重同名后注册覆盖前注册单一职责的扩展优先用工具包的drainPlugin()/enricherPlugin()简写读起来更直白。第3步为你的框架写适配器三行声明搞定如果你的框架还没有evlog/framework包自己接一个。工具包提供了与内置集成Hono、Express、Fastify、Elysia、NestJS完全相同的积木你只写框架特有的胶水代码。对于符合(ctx, next)中间件形状的 HTTP 框架用defineFrameworkIntegration声明式地写一个清单import { createLoggerStorage, defineFrameworkIntegration } from evlog/toolkit const { storage, useLogger } createLoggerStorage(...) const integration defineFrameworkIntegrationMyCtx({ name: my-framework, extractRequest: (ctx) ({ method, path, headers, requestId }), // ① 从哪读请求 attachLogger: (ctx, logger) { ctx.log logger }, // ② 把 logger 挂到哪 storage, }) export function evlog(options {}) { return async (ctx, next) { const { skipped, finish, runWith } integration.start(ctx, options) if (skipped) return next() await runWith(() next()) await finish({ status: ctx.status }) // ③ 响应结束后收尾 } }声明完路由过滤、drain 适配器、enricher、尾部采样、错误捕获、插件钩子、log.fork()、耗时统计全部免费获得。生命周期不贴合(ctx, next)的框架如拦截器模式可下沉到createMiddlewareLogger手写生命周期队列 worker、CLI、cron 这类非 HTTP 运行时则直接用createRequestLogger包住每个工作单元即可——enricher、drain 钩子和身份头依然全部生效。 参考实现就在仓库里直接照抄最快社区 drain 骨架完整契约 测试examples/community-adapter-skeleton/src/index.ts社区框架适配器骨架模拟一个MyFrameworkexamples/community-framework-skeleton/src/index.ts社区 enricher 骨架examples/community-enricher-skeleton/发布为社区包时记得把evlog声明为peerDependency而不是dependency避免用户安装时拉入第二份 evlog。常见问题drain 和插件有什么区别drain 只负责发出去是插件的一个特例插件可以订阅多个钩子并共享状态。单一目标用drainPlugin()包装即可。自建 drain 需要自己处理重试和超时吗不需要。defineHttpDrain默认重试2次、超时5000ms、错误隔离且目标宕机不影响业务管线继续运行。evlog/toolkit的 API 稳定吗官方标记为beta表面稳定所有内置集成都在用它但可能随社区反馈演化。总结evlog 的扩展设计非常统一drain、插件、框架适配器共享同一个工具包和同一套配置优先级显式 overrides →runtimeConfig→ 环境变量。掌握两个纯函数 声明式清单的心法你在半小时内就能让 evlog 接入任意后端、任意框架——这正是Digging through logs is not observability. Its hope. 之外的另一面让可扩展性成为默认值。延伸阅读扩展总览apps/docs/content/6.extend/0.overview.md自定义 drain 完整文档apps/docs/content/6.extend/8.custom-drains.md插件钩子详解apps/docs/content/6.extend/4.plugins.md框架适配器指南apps/docs/content/6.extend/10.custom-framework.md生产级 drain pipelineapps/docs/content/6.extend/9.drain-pipeline.md赞分享【免费下载链接】evlogDigging through logs is not observability. Its hope — wide events, structured errors, TypeScript-first, every runtime.项目地址https://gitcode.com/gh_mirrors/ev/evlog点击查看免费下载相关推荐Turbolinks自定义适配器开发扩展框架功能Turbolinks自定义适配器开发扩展框架功能 你是否在使用Turbolinks时遇到过这些问题默认进度条样式与应用风格不符需要在页面加载失败时执行自定前端StofDoctrineExtensionsBundle内部机制解析依赖注入和事件监听器的工作原理StofDoctrineExtensionsBundle内部机制解析依赖注入和事件监听器的工作原理 StofDoctrineExtensionsBundle是GrapesJS插件开发扩展框架功能的完整指南GrapesJS插件开发扩展框架功能的完整指南 本文深入探讨了GrapesJS插件系统的完整架构与开发实践。从核心的PluginManager设计理念出发详前端低代码UI组件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考