SuperAPI AI 工具集

create-evlog-enricher

编程与开发

查看项目

更新于 10-17 01:07

技能介绍

用途

该技能用于在 evlog 包中新增一个内置 enricher(增强器)。enricher 的作用是为宽事件(wide events)添加派生的上下文信息,例如部署元数据、租户上下文、功能开关等。每个 enricher 都构建在公共工具包原语 defineEnricher 之上(来自 evlog/toolkit),因此社区 enricher 与内置 enricher 具有相同的形状。

主要能力与改动范围

技能以“接触点清单”(Touchpoints Checklist)的形式规定需要改动的 7 个文件:

  1. packages/evlog/src/enrichers/index.ts:添加 enricher 源码(一次 defineEnricher 调用)。
  2. 同一文件中的 createDefaultEnrichers():决定该 enricher 是否加入默认组合。
  3. packages/evlog/test/toolkit/enrichers.test.ts:添加测试(每个 enricher 一个 describe 块)。
  4. apps/docs/content/5.use-cases/5.enrichers.md:添加 enricher 章节,并更新导入列表;若适用,更新“All built-in enrichers”默认组合说明。
  5. skills/review-logging-patterns/SKILL.md:在 Enrichers 小节的 Built-in: 行中加入该 enricher。
  6. packages/evlog/README.md:在 Built-in Enrichers 小节加入该 enricher(根 README.md 是指向它的符号链接)。
  7. .changeset/{name}-enricher.md:创建 changeset(minor)。

技能强调:在所有 7 个接触点处理完毕之前,任务不视为完成。

PR 标题格式为 feat(core): add the {name} enricher。由于 enrichers 位于核心包表面(evlog/enrichers),除非存在专用 scope,否则使用 core scope。

是否加入 createDefaultEnrichers()

createDefaultEnrichers() 通过 composeEnrichers(来自 ../shared/compose)组合 user agent、geo、request size 和 trace context。只有当新 enricher 普遍适用且只读取请求(headers/env)时才加入组合;任何需要服务特定设置或额外开销的 enricher 都保持为可选(opt-in)。改变默认组合会对每个现有 createDefaultEnrichers() 用户产生行为变更,必须在 changeset 中明确指出。

命名规范

  • {name}:camelCase,用于事件字段键,例如 userAgent。
  • {Name}:PascalCase,用于函数/接口名,例如 UserAgent。
  • {DISPLAY}:人类可读显示名,例如 User Agent。

使用方式:源码

在 packages/evlog/src/enrichers/index.ts 中添加 enricher,参考 references/enricher-template.md 获取完整带注释模板。

契约是 defineEnricher<T>({ name, field, compute }, options?)。只需提供一段逻辑:

  • compute(ctx):返回计算值(类型为 T),或返回 undefined 以跳过。

defineEnricher 负责其余部分:通过 mergeEventField 合并(遵循 options.overwrite,默认 false);错误隔离(抛出的异常被捕获并记录,不会向上传播);当 compute 返回 undefined 时跳过。

关键规则:

  • 使用工具包辅助函数:getHeader() 用于大小写不敏感的 header 查找,normalizeNumber() 用于数字字符串。二者来自 ../shared/headers(由 evlog/toolkit 重新导出)。
  • 单一事件字段:每个 enricher 在 ctx.event 上写入一个顶层字段。若 enricher 还必须固定顶层字段(如 createTraceContextEnricher 对 event.traceId / event.parentSpanId 所做),则将 defineEnricher 结果包裹在闭包中,可参考该 enricher 的模式。
  • 工厂模式:create{Name}Enricher(options: EnricherOptions = {}) 返回 defineEnricher(...) 的结果;正常情况下直接返回,或在 enricher 还需固定顶层字段时通过轻量闭包包装返回。
  • 无副作用:绝不抛出异常、绝不记录日志;出错时依赖 defineEnricher 的内置错误处理。
  • 导出 Info 类型:导出描述字段形状的 {Name}Info,与工厂函数一起导出。

测试

在 packages/evlog/test/toolkit/enrichers.test.ts 中添加测试,遵循现有结构(每个 enricher 一个 describe 块)和 packages/evlog/test/README.md 约定。必需的测试类别:

  1. 从来源设置字段:验证 enricher 正确填充事件字段,读取其实际读取的内容(ctx.request、ctx.response、process.env、ctx.event 或 headers)。
  2. 源数据缺失时跳过:验证所需输入不存在时不设置字段。
  3. 保留已有数据:验证 overwrite: false(默认)不会替换用户提供的字段。
  4. 请求时覆盖:验证 overwrite: true 替换已有字段。
  5. 处理边界情况:空字符串与畸形值,以及基于 header 的 enricher 的大小写不敏感查找。
  6. 默认组合:若 enricher 加入了 createDefaultEnrichers(),扩展该组合的测试。

文档更新

编辑 apps/docs/content/5.use-cases/5.enrichers.md:

  1. 将 enricher 加入顶部导入列表。
  2. 添加 ## {DISPLAY} 章节,遵循现有结构:一句话描述;**Sets:** event.{name};TypeScript 代码块 const enrich = create{Name}Enricher();Output shape 的 interface {Name}Info { // fields };Example output 的 JSON 示例。
  3. 若 enricher 加入了默认组合,更新“All built-in enrichers”章节文本。

自定义 enricher 编写文档单独位于 apps/docs/content/6.extend/5.custom-enrichers.md,除非工具包契约本身变化,否则无需改动。

在 skills/review-logging-patterns/SKILL.md(发布于 evlog.dev)中找到 Enrichers 部分,将新 enricher 加入 Built-in: 行。

在 packages/evlog/README.md(根 README.md 是指向它的符号链接)的 Built-in Enrichers 章节加入该 enricher。

创建 .changeset/{name}-enricher.md,使用 minor 版本提升,描述该 enricher 设置什么以及何时使用;若默认组合发生变化需明确提及。

验证

cd packages/evlog
pnpm run lint
pnpm run typecheck
pnpm run test
pnpm run build

适用场景与限制

适用于向 evlog 包贡献新的内置 enricher 的开发者场景,涉及源码、测试与文档的完整改动。限制:需严格完成全部 7 个接触点;仅有普遍适用且只读取 headers/env 的 enricher 才应加入默认组合,否则保持 opt-in,避免对现有用户造成行为变更。