导出到 PostHog

PostHog 是一个产品分析平台，帮助您了解用户行为并调试问题。将 Cloudflare Workers 应用程序遥测导出到 PostHog 后，您可以：

• 将日志与用户会话、事件和错误追踪数据关联
• 按严重级别、attributes 和自定义属性查询和过滤日志
• 将应用程序日志与会话回放连接，获得完整的调试上下文

本指南将引导您配置 Cloudflare Worker 应用程序，将符合 OpenTelemetry 标准的日志导出到 PostHog。

开始之前，请确保您拥有：

• 有效的 PostHog 账户 ↗（提供免费套餐）
• 要监控的已部署 Worker
• PostHog 项目 API 密钥

1. 登录 PostHog 账户 ↗
2. 导航到 Project settings（项目设置） ↗
3. 在项目详情部分找到 Project API key（项目 API 密钥）
4. 复制 API 密钥——此密钥与捕获事件和异常使用的密钥相同

API 密钥格式类似：phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

PostHog 根据数据区域有不同的端点：

您可以在 PostHog 项目设置中找到区域，或通过登录 PostHog 时的 URL 判断（us.posthog.com 或 eu.posthog.com）。

接下来，您将在 Cloudflare 仪表板中创建指向 PostHog 的目标。

1. 导航到 Cloudflare 账户的 Workers Observability ↗ 部分
2. 点击 Add destination（添加目标）
3. 配置日志目标：
   • Destination Name（目标名称）：posthog-logs（或任何描述性名称）
   • Destination Type（目标类型）：选择 Logs（日志）
   • OTLP Endpoint（OTLP 端点）：您的 PostHog 日志端点（例如 https://us.i.posthog.com/i/v1/logs 或 https://eu.i.posthog.com/i/v1/logs）
   • Custom Headers（自定义标头）：添加身份验证标头：
     • Header name：Authorization
     • Header value：Bearer <your-project-api-key>（例如 Bearer phc_xxxxx...）
4. 点击 Save（保存）

在 Cloudflare 仪表板中创建目标后，更新 Worker 配置以启用日志导出。

{
  "observability": {
    "logs": {
      "enabled": true,
      // Must match the destination name in the dashboard
      "destinations": ["posthog-logs"]
    }
  }
}

[observability.logs]
enabled = true
destinations = [ "posthog-logs" ]

更新配置后，部署 Worker 以使更改生效。

Worker 部署并开始接收流量后：

1. 登录 PostHog 账户 ↗
2. 在左侧边栏导航到 Logs（日志） 部分
3. Worker 日志将显示严重级别、时间戳和 attributes

您可以按以下条件过滤日志：

• 严重级别（trace、debug、info、warn、error、fatal）
• 时间范围
• 添加到日志条目的自定义 attributes
• 日志消息中的关键词

您可以使用带有结构化数据的标准 console 方法向日志添加自定义 attributes：

export default {
  async fetch(request, env) {
    // Basic logging
    console.log("Processing request");

    // Logs with additional context
    console.info("User action", {
      userId: "user_123",
      action: "api_call",
      path: new URL(request.url).pathname
    });

    // Error logging with details
    console.error("Request failed", {
      error: "Connection timeout",
      retryCount: 3
    });

    return new Response("OK");
  }
};

这些 attributes 可在 PostHog 日志界面中搜索和过滤。

1. 验证 API 密钥：确保使用的是项目 API 密钥（以 phc_ 开头），而非个人 API 密钥
2. 检查端点区域：确认使用的区域端点（US 或 EU）与 PostHog 实例匹配
3. 确认目标状态：在 Cloudflare 仪表板中，验证目标显示最近成功投递
4. 检查采样率：如果配置了采样率，并非所有日志都会被发送

如果目标状态显示身份验证错误：

• 确保 Authorization 标头值包含 Bearer 前缀，后跟 API 密钥
• 验证 API 密钥未在 PostHog 中被撤销或重新生成
• 或者，您可以通过使用 https://us.i.posthog.com/i/v1/logs?token=<your-project-api-key> 作为端点，将令牌作为查询参数传递

• PostHog Logs 文档 ↗
• PostHog 日志快速入门 ↗
• OpenTelemetry Logs 规范 ↗