创建evlog适配器指南：为evlog添加新内置适配器的完整步骤

create-evlog-adapter by hugorcd/evlog

478 周安装量

981 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/hugorcd/evlog --skill create-evlog-adapter

开发开发运维监控

🇨🇳中文介绍

创建 evlog 适配器

为 evlog 添加一个新的内置适配器。每个适配器都遵循相同的架构。本技能将引导您完成所有 8 个接触点。每一个接触点都是强制性的——不要跳过任何步骤。

PR 标题

推荐的拉取请求标题格式：

feat: add {name} adapter

具体措辞可能因适配器而异（例如 feat: add OTLP adapter、feat: add Axiom drain adapter），但应始终遵循 feat: 的约定式提交前缀。

接触点清单

| 文件 | 操作

---|---|---
1 | packages/evlog/src/adapters/{name}.ts | 创建适配器源代码
2 | packages/evlog/tsdown.config.ts | 添加构建入口
3 | packages/evlog/package.json | 添加和条目 4 | | 创建测试 5 | | 创建适配器文档页面（在之前） 6 | | 在概览页中添加适配器（链接、卡片、环境变量） 7 | | 在 Drain Adapters 表格中添加适配器行 8 | 重命名 | 确保添加新适配器后仍为最后一个

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

占位符	示例 (Datadog)	用途
`{name}`	`datadog`	文件名、导入路径、环境变量后缀
`{Name}`	`Datadog`	函数/接口名称中的 PascalCase
`{NAME}`	`DATADOG`	环境变量前缀中的 SCREAMING_CASE

步骤 1：适配器源代码

创建 packages/evlog/src/adapters/{name}.ts。

完整的带注释模板请参阅 references/adapter-template.md。

关键架构规则：

配置接口 —— 服务特定字段（API 密钥、端点等）加上可选的 timeout?: number
getRuntimeConfig() —— 从 ./_utils 导入（共享辅助函数，请勿在本地重新定义）
配置优先级（从高到低）：
- 传递给 create{Name}Drain() 的覆盖项
- runtimeConfig.evlog.{name}
- runtimeConfig.{name}
- 环境变量：NUXT_{NAME}_* 然后是 {NAME}_*
工厂函数 —— create{Name}Drain(overrides?: Partial<Config>) 返回 (ctx: DrainContext) => Promise<void>
导出的发送函数 —— sendTo{Name}(event, config) 和 sendBatchTo{Name}(events, config) 用于直接使用和可测试性
错误处理 —— 使用 try/catch 和 console.error('[evlog/{name}] ...')，切勿从 drain 函数中抛出错误
超时 —— 使用 AbortController，默认 5000 毫秒，可通过 config.timeout 配置
事件转换 —— 如果服务需要特定格式，请导出一个 to{Name}Event() 转换器

步骤 2：构建配置

在 packages/evlog/tsdown.config.ts 中，与现有适配器一起添加一个构建入口：

'adapters/{name}': 'src/adapters/{name}.ts',

将其放在最后一个适配器条目之后（当前 tsdown.config.ts 中是 hyperdx）。

步骤 3：包导出

在 packages/evlog/package.json 中，添加两个条目：

在 exports 中（在最后一个适配器之后，当前是 ./posthog）：

"./{name}": {
  "types": "./dist/adapters/{name}.d.mts",
  "import": "./dist/adapters/{name}.mjs"
}

在 typesVersions["*"] 中（在最后一个适配器之后）：

"{name}": [
  "./dist/adapters/{name}.d.mts"
]

创建 packages/evlog/test/adapters/{name}.test.ts。

完整的带注释模板请参阅 references/test-template.md。

必需的测试类别：

URL 构造（默认 + 自定义端点）
请求头（认证、内容类型、服务特定头）
请求体格式（JSON 结构需匹配服务 API）
错误处理（非 OK 响应应抛出状态码）
批量操作（sendBatchTo{Name}）
超时处理（默认 5000 毫秒 + 自定义）

步骤 5：适配器文档页面

创建 apps/docs/content/4.adapters/{n}.{name}.md，其中 {n} 是 custom.md 之前的下一个数字（custom 应始终为最后一个）。

使用现有的 Axiom 适配器页面（apps/docs/content/4.adapters/2.axiom.md）作为 frontmatter 结构、语气和章节的参考。关键章节包括：介绍、快速设置、配置（环境变量表格 + 优先级）、高级用法、在目标服务中查询、故障排除、直接 API 使用、后续步骤。

重要提示：多框架示例。 快速开始部分必须包含一个 ::code-group，其中包含所有支持框架（Nuxt/Nitro、Hono、Express、Fastify、Elysia、NestJS、Standalone）的标签页。不要只展示 Nitro 示例。请参考任何现有适配器页面的模式。

步骤 6：更新适配器概览页面

编辑 apps/docs/content/4.adapters/1.overview.md，在三个地方添加新适配器（遵循现有适配器的模式）：

Frontmatter links 数组 —— 添加一个包含图标和路径的链接条目
::card-group 部分 —— 在 Custom 卡片之前添加一个卡片块
零配置设置 .env 示例 —— 添加适配器的环境变量

步骤 7：更新 `skills/review-logging-patterns/SKILL.md`

在 skills/review-logging-patterns/SKILL.md（分发给用户的公共技能）中，找到 Drain Adapters 表格并添加一个新行：

| {Name} | `evlog/{name}` | `{NAME}_TOKEN`, `{NAME}_DATASET` (或等效变量) |

遵循现有行（Axiom、OTLP、PostHog、Sentry、Better Stack）的模式。不需要额外的使用示例块——表格条目已足够。

步骤 8：重命名 `custom.md`

如果新适配器的编号与 custom.md 冲突，请将 custom.md 重新编号为最后一个条目。例如，如果新适配器是 5.{name}.md，则将 5.custom.md 重命名为 6.custom.md。

完成所有步骤后，运行：

cd packages/evlog
bun run build    # 验证构建成功，包含新条目
bun run test     # 验证测试通过

🇺🇸English

Create evlog Adapter

Add a new built-in adapter to evlog. Every adapter follows the same architecture. This skill walks through all 8 touchpoints. Every single touchpoint is mandatory -- do not skip any.

PR Title

Recommended format for the pull request title:

feat: add {name} adapter

The exact wording may vary depending on the adapter (e.g., feat: add OTLP adapter, feat: add Axiom drain adapter), but it should always follow the feat: conventional commit prefix.

Touchpoints Checklist

| File | Action

---|---|---
1 | packages/evlog/src/adapters/{name}.ts | Create adapter source
2 | packages/evlog/tsdown.config.ts | Add build entry
3 | packages/evlog/package.json | Add exports + typesVersions entries
4 | packages/evlog/test/adapters/{name}.test.ts | Create tests
5 | apps/docs/content/4.adapters/{n}.{name}.md | Create adapter doc page (before custom.md)
6 | apps/docs/content/4.adapters/1.overview.md | Add adapter to overview (links, card, env vars)
7 | skills/review-logging-patterns/SKILL.md | Add adapter row in the Drain Adapters table
8 | Renumber custom.md | Ensure custom.md stays last after the new adapter

Important : Do NOT consider the task complete until all 8 touchpoints have been addressed.

Naming Conventions

Use these placeholders consistently:

Placeholder	Example (Datadog)	Usage
`{name}`	`datadog`	File names, import paths, env var suffix
`{Name}`	`Datadog`	PascalCase in function/interface names
`{NAME}`	`DATADOG`	SCREAMING_CASE in env var prefixes

Step 1: Adapter Source

Create packages/evlog/src/adapters/{name}.ts.

Read references/adapter-template.md for the full annotated template.

Key architecture rules:

Config interface -- service-specific fields (API key, endpoint, etc.) plus optional timeout?: number
getRuntimeConfig() -- import from ./_utils (shared helper, do NOT redefine locally)
Config priority (highest to lowest):
- Overrides passed to create{Name}Drain()
- runtimeConfig.evlog.{name}
- runtimeConfig.{name}
- Environment variables: NUXT_{NAME}_* then {NAME}_*
Factory function -- returns

Step 2: Build Config

Add a build entry in packages/evlog/tsdown.config.ts alongside the existing adapters:

'adapters/{name}': 'src/adapters/{name}.ts',

Place it after the last adapter entry (currently hyperdx in tsdown.config.ts).

Step 3: Package Exports

In packages/evlog/package.json, add two entries:

Inexports (after the last adapter, currently ./posthog):

"./{name}": {
  "types": "./dist/adapters/{name}.d.mts",
  "import": "./dist/adapters/{name}.mjs"
}

IntypesVersions["*"] (after the last adapter):

"{name}": [
  "./dist/adapters/{name}.d.mts"
]

Step 4: Tests

Create packages/evlog/test/adapters/{name}.test.ts.

Read references/test-template.md for the full annotated template.

Required test categories:

URL construction (default + custom endpoint)
Headers (auth, content-type, service-specific)
Request body format (JSON structure matches service API)
Error handling (non-OK responses throw with status)
Batch operations (sendBatchTo{Name})
Timeout handling (default 5000ms + custom)

Step 5: Adapter Documentation Page

Create apps/docs/content/4.adapters/{n}.{name}.md where {n} is the next number before custom.md (custom should always be last).

Use the existing Axiom adapter page (apps/docs/content/4.adapters/2.axiom.md) as a reference for frontmatter structure, tone, and sections. Key sections: intro, quick setup, configuration (env vars table + priority), advanced usage, querying in the target service, troubleshooting, direct API usage, next steps.

Important: multi-framework examples. The Quick Start section must include a ::code-group with tabs for all supported frameworks (Nuxt/Nitro, Hono, Express, Fastify, Elysia, NestJS, Standalone). Do not only show Nitro examples. See any existing adapter page for the pattern.

Step 6: Update Adapters Overview Page

Edit apps/docs/content/4.adapters/1.overview.md to add the new adapter in three places (follow the pattern of existing adapters):

Frontmatterlinks array -- add a link entry with icon and path
::card-group section -- add a card block before the Custom card
Zero-Config Setup.env example -- add the adapter's env vars

Step 7: Update `skills/review-logging-patterns/SKILL.md`

In skills/review-logging-patterns/SKILL.md (the public skill distributed to users), find the Drain Adapters table and add a new row:

| {Name} | `evlog/{name}` | `{NAME}_TOKEN`, `{NAME}_DATASET` (or equivalent) |

Follow the pattern of the existing rows (Axiom, OTLP, PostHog, Sentry, Better Stack). No additional usage example block is needed — the table entry is sufficient.

Step 8: Renumber `custom.md`

If the new adapter's number conflicts with custom.md, renumber custom.md to be the last entry. For example, if the new adapter is 5.{name}.md, rename 5.custom.md to 6.custom.md.

Verification

After completing all steps, run:

cd packages/evlog
bun run build    # Verify build succeeds with new entry
bun run test     # Verify tests pass

Weekly Installs

445

Repository

hugorcd/evlog

GitHub Stars

966

First Seen

Feb 8, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

codex379

opencode379

github-copilot378

gemini-cli377

amp375

kimi-cli373

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

105,000 周安装

create{Name}Drain(overrides?: Partial<Config>)

(ctx: DrainContext) => Promise<void>

Exported send functions -- sendTo{Name}(event, config) and sendBatchTo{Name}(events, config) for direct use and testability

Error handling -- try/catch with console.error('[evlog/{name}] ...'), never throw from the drain

Timeout -- AbortController with 5000ms default, configurable via config.timeout

Event transformation -- if the service needs a specific format, export a to{Name}Event() converter

创建evlog适配器指南：为evlog添加新内置适配器的完整步骤

🇨🇳中文介绍

创建 evlog 适配器

PR 标题

接触点清单

| 文件 | 操作

相关 Skills

命名约定

步骤 1：适配器源代码

步骤 2：构建配置

步骤 3：包导出

步骤 4：测试

步骤 5：适配器文档页面

步骤 6：更新适配器概览页面

步骤 7：更新 `skills/review-logging-patterns/SKILL.md`

步骤 8：重命名 `custom.md`

验证

🇺🇸English

Create evlog Adapter

PR Title

Touchpoints Checklist

| File | Action

Naming Conventions

Step 1: Adapter Source

Step 2: Build Config

Step 3: Package Exports

Step 4: Tests

Step 5: Adapter Documentation Page

Step 6: Update Adapters Overview Page

Step 7: Update `skills/review-logging-patterns/SKILL.md`

Step 8: Renumber `custom.md`

Verification

最新 Skills

创建evlog适配器指南：为evlog添加新内置适配器的完整步骤

🇨🇳中文介绍

创建 evlog 适配器

PR 标题

接触点清单

| 文件 | 操作

相关 Skills

命名约定

步骤 1：适配器源代码

步骤 2：构建配置

步骤 3：包导出

步骤 4：测试

步骤 5：适配器文档页面

步骤 6：更新适配器概览页面

步骤 7：更新 skills/review-logging-patterns/SKILL.md

步骤 8：重命名 custom.md

验证

🇺🇸English

Create evlog Adapter

PR Title

Touchpoints Checklist

| File | Action

Naming Conventions

Step 1: Adapter Source

Step 2: Build Config

Step 3: Package Exports

Step 4: Tests

Step 5: Adapter Documentation Page

Step 6: Update Adapters Overview Page

Step 7: Update skills/review-logging-patterns/SKILL.md

Step 8: Renumber custom.md

Verification

最新 Skills

步骤 7：更新 `skills/review-logging-patterns/SKILL.md`

步骤 8：重命名 `custom.md`

Step 7: Update `skills/review-logging-patterns/SKILL.md`

Step 8: Renumber `custom.md`