Back to Details

create-evlog-enricher

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Create evlog Enricher

创建evlog增强器

Add a new built-in enricher to evlog. Every enricher follows the same architecture. This skill walks through all 6 touchpoints. Every single touchpoint is mandatory -- do not skip any.
为evlog添加一个新的内置增强器。每个增强器都遵循相同的架构。本指南将带你走完全部6个环节。每个环节都是强制性的——请勿跳过任何一个。

PR Title

PR标题

Recommended format for the pull request title:
feat: add {name} enricher
The exact wording may vary depending on the enricher (e.g., 
feat: add user agent enricher
, 
feat: add geo enricher
), but it should always follow the 
feat:
conventional commit prefix.
拉取请求标题的推荐格式：
feat: add {name} enricher
具体措辞可根据增强器类型调整（例如
feat: add user agent enricher
、
feat: add geo enricher
），但必须始终遵循
feat:
的约定式提交前缀。

Touchpoints Checklist

环节检查清单

#FileAction
1
packages/evlog/src/enrichers/index.ts
Add enricher source
2
packages/evlog/test/enrichers.test.ts
Add tests
3
apps/docs/content/4.enrichers/2.built-in.md
Add enricher to built-in docs
4
apps/docs/content/4.enrichers/1.overview.md
Add enricher to overview cards
5
AGENTS.md
Add enricher to the "Built-in Enrichers" table
6
README.md
+ 
packages/evlog/README.md
Add enricher to README enrichers section
Important: Do NOT consider the task complete until all 6 touchpoints have been addressed.
序号文件操作
1
packages/evlog/src/enrichers/index.ts
添加增强器源代码
2
packages/evlog/test/enrichers.test.ts
添加测试用例
3
apps/docs/content/4.enrichers/2.built-in.md
在内置文档中添加该增强器的说明
4
apps/docs/content/4.enrichers/1.overview.md
在概览卡片中添加该增强器
5
AGENTS.md
在“内置增强器”表格中添加该增强器
6
README.md
+ 
packages/evlog/README.md
在README的增强器部分添加该增强器
重要提示：只有完成全部6个环节，才算任务完成。

Naming Conventions

命名规范

Use these placeholders consistently:
PlaceholderExample (UserAgent)Usage
{name}
userAgent
camelCase for event field key
{Name}
UserAgent
PascalCase in function/interface names
{DISPLAY}
User Agent
Human-readable display name
请统一使用以下占位符：
占位符示例（UserAgent）用途
{name}
userAgent
事件字段键名，采用小驼峰命名
{Name}
UserAgent
函数/接口名称，采用大驼峰命名
{DISPLAY}
User Agent
人类可读的显示名称

Step 1: Enricher Source

步骤1：增强器源代码

Add the enricher to 
packages/evlog/src/enrichers/index.ts
.
Read references/enricher-template.md for the full annotated template.
Key architecture rules:
  1. Info interface -- define the shape of the enricher output (e.g., 
    UserAgentInfo
    , 
    GeoInfo
    )
  2. Factory function -- 
    create{Name}Enricher(options?: EnricherOptions)
    returns 
    (ctx: EnrichContext) => void
  3. Uses 
    EnricherOptions
     -- accepts 
    { overwrite?: boolean }
    to control merge behavior
  4. Uses 
    mergeEventField()
     -- merge computed data with existing event fields, respecting 
    overwrite
  5. Uses 
    getHeader()
     -- case-insensitive header lookup helper
  6. Sets a single event field -- 
    ctx.event.{name} = mergedValue
  7. Early return -- skip enrichment if required headers are missing
  8. No side effects -- enrichers only mutate 
    ctx.event
    , never throw or log
将增强器添加至
packages/evlog/src/enrichers/index.ts
。
请阅读references/enricher-template.md获取完整的带注释模板。
核心架构规则：
  1. 信息接口——定义增强器输出的结构（例如
    UserAgentInfo
    、
    GeoInfo
    ）
  2. 工厂函数——
    create{Name}Enricher(options?: EnricherOptions)
    返回
    (ctx: EnrichContext) => void
  3. 使用
    EnricherOptions
    ——接受
    { overwrite?: boolean }
    参数以控制合并行为
  4. 使用
    mergeEventField()
    ——将计算得到的数据与现有事件字段合并，尊重
    overwrite
    配置
  5. 使用
    getHeader()
    ——大小写不敏感的头信息查找工具函数
  6. 设置单个事件字段——
    ctx.event.{name} = mergedValue
  7. 提前返回——如果缺少必要的头信息则跳过增强处理
  8. 无副作用——增强器仅修改
    ctx.event
    ，不会抛出异常或记录日志

Step 2: Tests

步骤2：测试用例

Add tests to 
packages/evlog/test/enrichers.test.ts
.
Required test categories:
  1. Sets field from headers -- verify the enricher populates the event field correctly
  2. Skips when header missing -- verify no field is set when the required header is absent
  3. Preserves existing data -- verify 
    overwrite: false
    (default) doesn't replace user-provided fields
  4. Overwrites when requested -- verify 
    overwrite: true
    replaces existing fields
  5. Handles edge cases -- empty strings, malformed values, case-insensitive header names
Follow the existing test structure in 
enrichers.test.ts
-- each enricher has its own 
describe
block.
将测试用例添加至
packages/evlog/test/enrichers.test.ts
。
需要覆盖的测试类别：
  1. 从请求头设置字段——验证增强器能否正确填充事件字段
  2. 缺少请求头时跳过处理——验证当必要头信息缺失时不会设置字段
  3. 保留现有数据——验证默认的
    overwrite: false
    不会替换用户提供的字段
  4. 按配置覆盖数据——验证
    overwrite: true
    会替换现有字段
  5. 处理边缘情况——空字符串、格式错误的值、大小写不敏感的头名称
请遵循
enrichers.test.ts
中已有的测试结构——每个增强器都有自己的
describe
块。

Step 3: Update Built-in Docs

步骤3：更新内置文档

Edit 
apps/docs/content/4.enrichers/2.built-in.md
to add a new section for the enricher.
Each enricher section follows this structure:
markdown
undefined
编辑
apps/docs/content/4.enrichers/2.built-in.md
，为该增强器添加新的章节。
每个增强器章节遵循以下结构：
markdown
undefined

{DISPLAY}

{DISPLAY}

[One-sentence description of what the enricher does.]
Sets: 
event.{name}
```typescript const enrich = create{Name}Enricher() ```
Output shape:
```typescript interface {Name}Info { // fields } ```
Example output:
```json { "{name}": { // example values } } ```

Add any relevant callouts for platform-specific notes or limitations.
[一句话描述该增强器的功能。]
设置字段： 
event.{name}
```typescript const enrich = create{Name}Enricher() ```
输出结构：
```typescript interface {Name}Info { // 字段 } ```
示例输出：
```json { "{name}": { // 示例值 } } ```

可添加任何与平台相关的注意事项或限制说明。

Step 4: Update Overview Page

步骤4：更新概览页面

Edit 
apps/docs/content/4.enrichers/1.overview.md
to add a card for the new enricher in the 
::card-group
section (before the Custom card):
markdown
  :::card
  ---
  icon: i-lucide-{icon}
  title: {DISPLAY}
  to: /enrichers/built-in#{anchor}
  ---
  [Short description.]
  :::
编辑
apps/docs/content/4.enrichers/1.overview.md
，在
::card-group
部分（Custom卡片之前）为新增强器添加一张卡片：
markdown
  :::card
  ---
  icon: i-lucide-{icon}
  title: {DISPLAY}
  to: /enrichers/built-in#{anchor}
  ---
  [简短描述。]
  :::

Step 5: Update AGENTS.md

步骤5：更新AGENTS.md

Add the new enricher to the "Built-in Enrichers" table in the root 
AGENTS.md
file, in the "Event Enrichment" section:
markdown
| {DISPLAY} | `evlog/enrichers` | `{name}` | [Description] |
在根目录的
AGENTS.md
文件的“内置增强器”表格中，将新增强器添加至“事件增强”部分：
markdown
| {DISPLAY} | `evlog/enrichers` | `{name}` | [描述] |

Step 6: Update READMEs

步骤6：更新README文件

Add the enricher to the enrichers section in both 
README.md
and 
packages/evlog/README.md
. Both files should list all built-in enrichers with their event fields and output shapes.
在
README.md
和
packages/evlog/README.md
的增强器部分添加该增强器。两个文件都应列出所有内置增强器及其事件字段和输出结构。

Verification

验证

After completing all steps, run:
bash
cd packages/evlog
bun run build    # Verify build succeeds
bun run test     # Verify tests pass
完成所有步骤后，运行以下命令：
bash
cd packages/evlog
bun run build    # 验证构建成功
bun run test     # 验证测试通过