PostHog へエクスポートする

PostHog はプロダクト分析プラットフォームです。ユーザー行動の把握と問題のデバッグに使えます。Cloudflare Workers アプリのテレメトリを PostHog にエクスポートすると、次のことができます。

• ログをユーザーセッション、イベント、エラートラッキングデータと突き合わせる
• 重大度、属性、カスタムプロパティでログを照会・フィルタする
• アプリログをセッションリプレイにつなぎ、デバッグの全体像を得る

このガイドでは、Cloudflare Worker アプリが OpenTelemetry 準拠のログを PostHog にエクスポートする設定を説明します。

始める前に、次を用意します。

• 有効な PostHog アカウント ↗（無料プランあり）
• 監視したいデプロイ済みの Worker
• PostHog のプロジェクト API キー

1. PostHog アカウント ↗ にログインします
2. Project settings ↗ を開きます
3. プロジェクト詳細で Project API key を探します
4. API キーをコピーします。イベントや例外のキャプチャに使うキーと同じです

API キーは次のような形式です: phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

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: 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 をクリックします

ダッシュボードで送信先を作成したら、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 のログが、重大度、タイムスタンプ、属性付きで表示されます

次の条件でログをフィルタできます。

• Severity level（trace、debug、info、warn、error、fatal）
• Time range
• ログエントリに付与した カスタム属性
• ログメッセージ内の キーワード

標準の console メソッドと構造化データで、ログにカスタム属性を追加できます。

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");
  }
};

これらの属性は、PostHog のログ画面で検索・フィルタできます。

1. API キーを確認する: 個人用 API キーではなく、プロジェクト API キー（phc_ で始まる）を使っていることを確認します
2. エンドポイントのリージョンを確認する: PostHog インスタンスと一致するリージョンエンドポイント（US または EU）を使っていることを確認します
3. 送信先の状態を確認する: Cloudflare ダッシュボードで、送信先に最近の成功した配信が表示されていることを確認します
4. サンプリングレートを確認する: サンプリングレートを設定している場合、すべてのログが送られるわけではありません

送信先の状態に認証エラーが出る場合:

• Authorization ヘッダーの値に、Bearer プレフィックスのあとに API キーが続いていることを確認します
• PostHog で API キーが失効または再発行されていないことを確認します
• 代わりに、エンドポイントを https://us.i.posthog.com/i/v1/logs?token=<your-project-api-key> にして、トークンをクエリパラメータで渡すこともできます

• PostHog Logs documentation ↗
• PostHog Getting Started with Logs ↗
• OpenTelemetry Logs specification ↗