适配器

PostHog 适配器

通过 OTLP 将广泛事件发送到 PostHog Logs，用于结构化日志查询、调试和监控。

PostHog 是一个开源的产品分析平台。evlog 的 PostHog 适配器通过标准 OTLP 格式将你的广泛事件发送到 PostHog Logs，为你提供一个带有过滤、搜索和尾部模式的专用日志查看器，并可利用现有的 PostHog API 密钥。

Prompt

添加 PostHog 排水适配器以将 evlog 广泛事件发送到 PostHog Logs。

1. 确认我正在使用的框架并遵循其 evlog 集成模式
2. 如果尚未安装 evlog，请进行安装
3. 从 'evlog/posthog' 导入 createPostHogDrain
4. 将 createPostHogDrain() 集成到我的框架的排水配置中
5. 设置 POSTHOG_API_KEY 环境变量
6. 可选地设置 POSTHOG_HOST 以用于欧盟或自托管实例
7. 通过触发请求并检查 PostHog > 日志进行测试

适配器文档: https://www.evlog.dev/adapters/posthog
框架设置: https://www.evlog.dev/frameworks

安装

PostHog 适配器已与 evlog 捆绑在一起：

src/index.ts

import { createPostHogDrain } from 'evlog/posthog'

快速开始

1. 获取 PostHog 项目 API 密钥

登录你的 PostHog 控制面板
进入设置 > 项目 > 项目 API 密钥
复制密钥（以 phc_ 开头）

2. 设置环境变量

.env

POSTHOG_API_KEY=phc_your-project-api-key

3. 将排水管道连接到你的框架

// server/plugins/evlog-drain.ts
import { createPostHogDrain } from 'evlog/posthog'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('evlog:drain', createPostHogDrain())
})

import { createPostHogDrain } from 'evlog/posthog'

app.use(evlog({ drain: createPostHogDrain() }))

import { createPostHogDrain } from 'evlog/posthog'

app.use(evlog({ drain: createPostHogDrain() }))

import { createPostHogDrain } from 'evlog/posthog'

await app.register(evlog, { drain: createPostHogDrain() })

import { createPostHogDrain } from 'evlog/posthog'

app.use(evlog({ drain: createPostHogDrain() }))

import { createPostHogDrain } from 'evlog/posthog'

EvlogModule.forRoot({ drain: createPostHogDrain() })

import { createPostHogDrain } from 'evlog/posthog'

initLogger({ drain: createPostHogDrain() })

就这样！现在你的广泛事件将以完整的 OTLP 结构（包括严重级别、跟踪上下文和结构化属性）出现在 PostHog 日志中。

配置

适配器从多个来源读取配置（优先级从高到低）：

传递给 createPostHogDrain() 的覆盖项
运行时配置 runtimeConfig.posthog（仅限 Nuxt/Nitro）
环境变量（POSTHOG_* 或 NUXT_POSTHOG_*）

环境变量

变量	Nuxt 别名	描述
`POSTHOG_API_KEY`	`NUXT_POSTHOG_API_KEY`	项目 API 密钥（以 `phc_` 开头）
`POSTHOG_HOST`	`NUXT_POSTHOG_HOST`	PostHog 主机 URL（用于欧盟或自托管）

运行时配置（仅限 Nuxt）

通过 nuxt.config.ts 进行配置以实现类型安全的配置：

nuxt.config.ts

export default defineNuxtConfig({
  runtimeConfig: {
    posthog: {
      apiKey: '', // 通过 NUXT_POSTHOG_API_KEY 设置
      host: '', // 通过 NUXT_POSTHOG_HOST 设置
    },
  },
})

覆盖选项

直接传递选项以覆盖任何配置：

server/plugins/evlog-drain.ts

const drain = createPostHogDrain({
  host: 'https://eu.i.posthog.com',
  timeout: 10000,
})

完整配置参考

选项	类型	默认值	描述
`apiKey`	`string`	-	项目 API 密钥（必需）
`host`	`string`	`https://us.i.posthog.com`	PostHog 主机 URL
`timeout`	`number`	`5000`	请求超时时间（毫秒）

工作原理

在底层，createPostHogDrain() 使用 PostHog 特定的默认值包装 OTLP 适配器的 sendBatchToOTLP()：

端点：{host}/i/v1/logs（PostHog 的 OTLP 日志摄取端点）
认证：Authorization: Bearer {apiKey} 头部
格式：标准 OTLP ExportLogsServiceRequest，包含严重级别、跟踪上下文和结构化属性

区域

PostHog 提供美国和欧盟云托管。设置 host 以匹配你的区域：

区域	主机
美国（默认）	`https://us.i.posthog.com`
欧盟	`https://eu.i.posthog.com`
自托管	你的实例 URL

.env

# 欧盟区域
POSTHOG_API_KEY=phc_xxx
POSTHOG_HOST=https://eu.i.posthog.com

在 PostHog 中查询日志

一旦日志开始流动，请在 PostHog 的日志选项卡中查询它们：

进入日志，并按服务、严重级别或任何结构化属性进行过滤
使用搜索栏查找特定日志条目
点击日志条目以查看所有结构化属性

PostHog 事件（自定义事件）

如果你更喜欢将日志作为 PostHog 自定义事件发送（例如用于产品分析、群组或漏斗），请使用 createPostHogEventsDrain()：

server/plugins/evlog-drain.ts

import { createPostHogEventsDrain } from 'evlog/posthog'

const drain = createPostHogEventsDrain({
  eventName: 'server_request',
  distinctId: 'my-backend-service',
})

然后像传递 createPostHogDrain() 那样将 drain 传递给你的框架（参见上方的快速开始）。

自定义事件会计入你的 PostHog 事件配额。PostHog 日志（默认的 createPostHogDrain()）成本要低得多。

事件配置

选项	类型	默认值	描述
`apiKey`	`string`	-	项目 API 密钥（必需）
`host`	`string`	`https://us.i.posthog.com`	PostHog 主机 URL
`eventName`	`string`	`evlog_wide_event`	PostHog 事件名称
`distinctId`	`string`	`event.service`	覆盖所有事件的 `distinct_id`
`timeout`	`number`	`5000`	请求超时时间（毫秒）

事件格式

evlog 将广泛事件映射到 PostHog 事件：

evlog 字段	PostHog 字段
`config.distinctId` 或 `userId` 或 `service`	`distinct_id`（回退链）
`timestamp`	`timestamp`
`level`	`properties.level`
`service`	`properties.service`
`environment`	`properties.environment`
所有其他字段	`properties.*`

唯一 ID 解析

distinct_id 遵循回退链：

config.distinctId - 在 createPostHogEventsDrain() 中的显式覆盖
event.userId - 如果存在字符串则自动获取
event.service - 最终回退

日志 vs 事件

	`createPostHogDrain()`	`createPostHogEventsDrain()`
格式	OTLP 日志 (`/i/v1/logs`)	PostHog 事件 (`/batch/`)
PostHog UI	日志查看器	事件探索器
成本	较低（专用的日志管道）	较高（计入事件）
最佳用途	调试、日志搜索、监控	产品分析、群组、漏斗

你可以同时使用两种排水管道以获得最佳效果：

server/plugins/evlog-drain.ts

import { createPostHogDrain, createPostHogEventsDrain } from 'evlog/posthog'

const logs = createPostHogDrain()
const events = createPostHogEventsDrain()

const drain = async (ctx) => {
  await Promise.allSettled([logs(ctx), events(ctx)])
}

故障排除

缺少 API 密钥错误

Console

[evlog/posthog] Missing apiKey. Set POSTHOG_API_KEY env var or pass to createPostHogDrain()

确保环境变量已设置，并且在添加后重新启动了服务器。

事件未出现

PostHog 异步处理事件。事件可能需要短暂延迟（通常不到 1 分钟）才能在仪表板中显示。

检查服务器控制台是否有 [evlog/posthog] 错误信息
验证 API 密钥是否正确并以 phc_ 开头
确认 host 与你的 PostHog 区域（美国或欧盟）匹配

区域错误

如果你在 PostHog EU 上但使用了默认的美国主机，事件交付将失败，并且适配器会在服务器控制台记录错误（例如 [evlog/posthog]）。设置正确的主机：

.env

POSTHOG_HOST=https://eu.i.posthog.com

直接 API 使用

对于高级用例，你可以使用更低级别的函数：

server/utils/posthog.ts

import { sendToPostHog, sendBatchToPostHog } from 'evlog/posthog'

// 发送单个事件到 PostHog 日志（OTLP）
await sendToPostHog(event, {
  apiKey: 'phc_xxx',
})

// 批量发送多个事件
await sendBatchToPostHog(events, {
  apiKey: 'phc_xxx',
})

对于自定义事件，使用事件专用函数：

server/utils/posthog.ts

import { sendToPostHogEvents, sendBatchToPostHogEvents, toPostHogEvent } from 'evlog/posthog'

// 发送单个自定义事件
await sendToPostHogEvents(event, {
  apiKey: 'phc_xxx',
})

// 批量发送多个自定义事件
await sendBatchToPostHogEvents(events, {
  apiKey: 'phc_xxx',
})

// 转换为 PostHog 格式（用于检查）
const posthogEvent = toPostHogEvent(event, { apiKey: 'phc_xxx' })

下一步

Axiom 适配器 - 将日志发送到 Axiom
OTLP 适配器 - 通过 OpenTelemetry 协议发送日志
自定义适配器 - 构建你自己的适配器
最佳实践 - 安全和生产提示

Edit this pageorReport an issue

OTLP

通过 OpenTelemetry Protocol (OTLP) 向 Grafana、Datadog、Honeycomb 以及任何兼容的后端发送日志。支持 gRPC 和 HTTP 传输。

Sentry

将结构化日志发送到 Sentry Logs 以支持高基数查询和调试。通过环境变量即可实现零配置设置。