---
title: "扩展 evlog"
description: "观察流经管道的内容、接入管道，或构建你自己的模块。这里展示了 evlog 暴露的所有扩展点。"
canonical_url: "https://evlog.zhcndoc.com/extend/overview"
---
# 扩展 evlog

> 观察流经管道的内容、接入管道，或构建你自己的模块。这里展示了 evlog 暴露的所有扩展点。

evlog 的设计支持从两端进行扩展。你可以**观察**流经管道的内容（不改变管道），**接入**管道（增强、决定保留哪些内容、响应生命周期事件），或**构建你自己的模块**（用于不受支持目标的自定义排出器、自定义框架集成）。本节中的每个页面都附带一个 `::prompt` 块，你可以将其放入 Cursor / Claude，以便在自己的应用中搭建集成。

## 心智模型

```text
应用代码
        │
        │  发出
        ▼
┌──────────────────────────────────────────────────────────────────┐
│   evlog 管道                                                     │
│                                                                  │
│   请求生命周期  →  增强  →  尾部采样  →  排出                    │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
     │                                                  │
     │  观察（不修改）                                  │  发送
     ▼                                                  ▼
┌─────────────────────────────────────────┐    ┌─────────────────────┐
│   流（进程内 + SSE 桥接）                │    │   自定义排出器       │
│   fs 读取器（NDJSON 历史记录）           │    │   排出管道           │
│   诊断通道（evlog.event）                │    │   （批处理 + 扇出）  │
│   消费者方案（开发者工具、仪表板）       │    │                     │
└─────────────────────────────────────────┘    └─────────────────────┘
```

## 三种扩展方式

### 观察管道（不改变内容）

订阅事件，而不改变发出的内容。流是实时数据源，fs reader 是历史日志，诊断通道允许消费者仅通过通道名称进行订阅，而消费者示例则展示如何将其中任意一种连接到开发工具、仪表板、CLI tail，或 `curl` + `jq`。

<table>
<thead>
  <tr>
    <th>
      你想要……
    </th>
    
    <th>
      使用
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      订阅实时事件（进程内，或通过 SSE 供浏览器 / CLI 使用）
    </td>
    
    <td>
      <a href="https://evlog.zhcndoc.com/extend/stream">
        流
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      从磁盘重放或持续读取历史事件
    </td>
    
    <td>
      <a href="https://evlog.zhcndoc.com/extend/fs-reader">
        FS reader
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      构建一个小型消费者面板、开发工具，或连接到 <code>
        curl
      </code>
      
       + <code>
        jq
      </code>
      
       的管道
    </td>
    
    <td>
      <a href="https://evlog.zhcndoc.com/extend/consumer-recipes">
        消费者示例
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      让消费者无需导入 evlog 即可订阅，或访问 Cloudflare Tail Worker
    </td>
    
    <td>
      <a href="https://evlog.zhcndoc.com/extend/diagnostics-channel">
        诊断通道
      </a>
    </td>
  </tr>
</tbody>
</table>

### 接入管道

在一个或多个生命周期阶段接入管道。下面四个页面涵盖了完整的扩展面。只有一个关注点时选择其中一个；有多个关注点时选择 `definePlugin`。

<table>
<thead>
  <tr>
    <th>
      你想要……
    </th>
    
    <th>
      使用
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      从一个统一的对象响应生命周期事件（多个 hooks 共享状态）
    </td>
    
    <td>
      <a href="https://evlog.zhcndoc.com/extend/plugins">
        插件
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      为每个事件自动添加一个派生字段
    </td>
    
    <td>
      <a href="https://evlog.zhcndoc.com/extend/custom-enrichers">
        自定义增强器
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      事后决定是否保留某个事件（status、duration、自定义逻辑）
    </td>
    
    <td>
      <a href="https://evlog.zhcndoc.com/extend/tail-sampling">
        尾部采样
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      在接收端标识你的 evlog 流量（覆盖 <code>
        User-Agent
      </code>
      
       / <code>
        X-Evlog-Source
      </code>
      
      ）
    </td>
    
    <td>
      <a href="https://evlog.zhcndoc.com/extend/identity-headers">
        身份标头
      </a>
    </td>
  </tr>
</tbody>
</table>

### 构建你自己的模块

当内置适配器或框架集成无法满足你的需求时，这个工具包允许你以相同的形态和易用性构建自己的方案。

<table>
<thead>
  <tr>
    <th>
      你想要……
    </th>
    
    <th>
      使用
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      将事件发送到没有内置适配器的后端（HTTP 或任何其他传输方式）
    </td>
    
    <td>
      <a href="https://evlog.zhcndoc.com/extend/custom-drains">
        自定义 drains
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      为生产环境将任意 drain 封装为 batch + retry + fanout
    </td>
    
    <td>
      <a href="https://evlog.zhcndoc.com/extend/drain-pipeline">
        Drain 管道
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      支持列表中没有的框架，或非 HTTP 运行时
    </td>
    
    <td>
      <a href="https://evlog.zhcndoc.com/extend/custom-framework">
        自定义框架集成
      </a>
    </td>
  </tr>
</tbody>
</table>

## 哪些内容在哪里可用

只有 [流](https://evlog.zhcndoc.com/extend/stream)（进程内总线 + SSE 桥接）是**仅限本地**的：它存在于单个 Node / Bun / Deno 进程中，无法在无服务器平台（Vercel Functions、Cloudflare Workers、AWS Lambda）上运行。[流页面](https://evlog.zhcndoc.com/extend/stream)详细解释了这一限制。

其他所有内容，从 [FS reader](https://evlog.zhcndoc.com/extend/fs-reader)、[插件](https://evlog.zhcndoc.com/extend/plugins)、[自定义增强器](https://evlog.zhcndoc.com/extend/custom-enrichers)、[尾部采样](https://evlog.zhcndoc.com/extend/tail-sampling)、[身份标头](https://evlog.zhcndoc.com/extend/identity-headers)、[自定义 drains](https://evlog.zhcndoc.com/extend/custom-drains)、[Drain 管道](https://evlog.zhcndoc.com/extend/drain-pipeline) 到 [自定义框架集成](https://evlog.zhcndoc.com/extend/custom-framework)，都可以在 evlog 运行的任何地方运行。

---

- [流](https://evlog.zhcndoc.com/extend/stream)
- [插件](https://evlog.zhcndoc.com/extend/plugins)
- [自定义排出器](https://evlog.zhcndoc.com/extend/custom-drains)


## Sitemap

See the full [sitemap](https://evlog.zhcndoc.com/sitemap.md) for all pages.