Skip to content

Commit 25bf92e

Browse files
Add PostHog export documentation and images for Cloudflare Workers observability
- Introduced a new guide on exporting OpenTelemetry logs to PostHog, detailing prerequisites, configuration steps, and troubleshooting tips. - Added two images to illustrate the PostHog logs view and the Cloudflare destination configuration for logs. - Updated the existing documentation to include PostHog as a supported observability provider.
1 parent 4f3add0 commit 25bf92e

File tree

4 files changed

+162
-0
lines changed

4 files changed

+162
-0
lines changed
138 KB
Loading
399 KB
Loading

src/content/docs/workers/observability/exporting-opentelemetry-data/index.mdx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ Below are common OTLP endpoint formats for popular observability providers. Refe
2828
| [**Grafana Cloud**](/workers/observability/exporting-opentelemetry-data/grafana-cloud/) | `https://otlp-gateway-{region}.grafana.net/otlp/v1/traces` | `https://otlp-gateway-{region}.grafana.net/otlp/v1/logs`[^1] |
2929
| [**Axiom**](/workers/observability/exporting-opentelemetry-data/axiom/) | `https://api.axiom.co/v1/traces` | `https://api.axiom.co/v1/logs` |
3030
| [**Sentry**](/workers/observability/exporting-opentelemetry-data/sentry/) | `https://{HOST}/api/{PROJECT_ID}/integration/otlp/v1/traces` | `https://{HOST}/api/{PROJECT_ID}/integration/otlp/v1/logs` |
31+
| [**PostHog**](/workers/observability/exporting-opentelemetry-data/posthog/) | Not supported | `https://us.i.posthog.com/i/v1/logs` |
3132
| [**Datadog**](https://docs.datadoghq.com/opentelemetry/setup/otlp_ingest/) | Coming soon, pending release from Datadog | `https://otlp.{SITE}.datadoghq.com/v1/logs` |
3233

3334
:::note[Authentication]
Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
---
2+
pcx_content_type: how-to
3+
title: Export to PostHog
4+
sidebar:
5+
order: 5
6+
---
7+
8+
import {WranglerConfig} from "~/components";
9+
10+
PostHog is a product analytics platform that helps you understand user behavior and debug issues. By exporting your Cloudflare Workers application telemetry to PostHog, you can:
11+
12+
- Correlate logs with user sessions, events, and error tracking data
13+
- Query and filter logs by severity, attributes, and custom properties
14+
- Connect application logs to session replays for full debugging context
15+
16+
![PostHog logs view with attributes expanded and a timeline view at the top](~/assets/images/workers-observability/sentry-example.png)
17+
18+
This guide will walk you through configuring your Cloudflare Worker application to export OpenTelemetry-compliant logs to PostHog.
19+
20+
## Prerequisites
21+
22+
Before you begin, ensure you have:
23+
24+
- An active [PostHog account](https://app.posthog.com/signup) (free tier available)
25+
- A deployed Worker that you want to monitor
26+
- Your PostHog project API key
27+
28+
## Step 1: Get your PostHog project API key
29+
30+
1. Log in to your [PostHog account](https://app.posthog.com/)
31+
2. Navigate to the [**Project settings**](https://app.posthog.com/settings/project#selectedSetting=variables&setting=variables)
32+
3. Find your **Project API key** in the project details section
33+
4. Copy the API key - this is the same key used for capturing events and exceptions
34+
35+
The API key should look something like: `phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
36+
37+
## Step 2: Determine your PostHog region endpoint
38+
39+
PostHog has different endpoints depending on your data region:
40+
41+
| Region | Logs Endpoint |
42+
| ------ | ------------- |
43+
| **US** (default) | `https://us.i.posthog.com/i/v1/logs` |
44+
| **EU** | `https://eu.i.posthog.com/i/v1/logs` |
45+
46+
You can find your region in your PostHog project settings or by checking the URL when logged into PostHog (either `us.posthog.com` or `eu.posthog.com`).
47+
48+
## Step 3: Configure Cloudflare Logs destination
49+
50+
:::caution
51+
Cloudflare Workers Observability only supports exporting **logs** to PostHog at this time. Exporting **traces** to PostHog is not currently supported.
52+
:::
53+
54+
Now you'll create a destination in the Cloudflare dashboard that points to PostHog.
55+
56+
1. Navigate to your Cloudflare account's [Workers Observability](https://dash.cloudflare.com/?to=/:account/workers-and-pages/observability/pipelines) section
57+
2. Click **Add destination**
58+
3. Configure your logs destination:
59+
- **Destination Name**: `posthog-logs` (or any descriptive name)
60+
- **Destination Type**: Select **Logs**
61+
- PostHog does not support importing Cloudflare traces at this time.
62+
- **OTLP Endpoint**: Your PostHog logs endpoint (e.g., `https://us.i.posthog.com/i/v1/logs` or `https://eu.i.posthog.com/i/v1/logs`)
63+
- **Custom Headers**: Add the authentication header:
64+
- Header name: `Authorization`
65+
- Header value: `Bearer <your-project-api-key>` (e.g., `Bearer phc_xxxxx...`)
66+
4. Click **Save**
67+
68+
![Cloudflare destination configuration for PostHog logs with destination name, type selection, OTLP endpoint, and custom headers](~/assets/images/workers-observability/posthog-example-destination-modal.png)
69+
70+
## Step 4: Configure your Worker
71+
72+
With your destination created in the Cloudflare dashboard, update your Worker's configuration to enable logs export.
73+
74+
<WranglerConfig>
75+
76+
```json
77+
{
78+
"observability": {
79+
"logs": {
80+
"enabled": true,
81+
// Must match the destination name in the dashboard
82+
"destinations": ["posthog-logs"]
83+
}
84+
}
85+
}
86+
```
87+
88+
</WranglerConfig>
89+
90+
After updating your configuration, deploy your Worker for the changes to take effect.
91+
92+
:::note
93+
It may take a few minutes after deployment for logs to appear in PostHog.
94+
:::
95+
96+
## Step 5: View logs in PostHog
97+
98+
Once your Worker is deployed and receiving traffic:
99+
100+
1. Log in to your [PostHog account](https://app.posthog.com/)
101+
2. Navigate to the **Logs** section in the left sidebar
102+
3. Your Worker logs will appear with severity levels, timestamps, and attributes
103+
104+
You can filter logs by:
105+
- **Severity level** (trace, debug, info, warn, error, fatal)
106+
- **Time range**
107+
- **Custom attributes** added to your log entries
108+
- **Keywords** in log messages
109+
110+
## Adding custom attributes to logs
111+
112+
You can add custom attributes to your logs using standard `console` methods with structured data:
113+
114+
```javascript
115+
export default {
116+
async fetch(request, env) {
117+
// Basic logging
118+
console.log("Processing request");
119+
120+
// Logs with additional context
121+
console.info("User action", {
122+
userId: "user_123",
123+
action: "api_call",
124+
path: new URL(request.url).pathname
125+
});
126+
127+
// Error logging with details
128+
console.error("Request failed", {
129+
error: "Connection timeout",
130+
retryCount: 3
131+
});
132+
133+
return new Response("OK");
134+
}
135+
};
136+
```
137+
138+
These attributes will be searchable and filterable in the PostHog logs interface.
139+
140+
## Troubleshooting
141+
142+
### Logs not appearing in PostHog
143+
144+
1. **Verify your API key**: Ensure you're using your project API key (starts with `phc_`), not a personal API key
145+
2. **Check the endpoint region**: Confirm you're using the correct regional endpoint (US or EU) matching your PostHog instance
146+
3. **Confirm destination status**: In the Cloudflare dashboard, verify your destination shows a recent successful delivery
147+
4. **Check sampling rate**: If you've configured a sampling rate, not all logs may be sent
148+
149+
### Authentication errors
150+
151+
If you see authentication errors in your destination status:
152+
153+
- Ensure the Authorization header value includes `Bearer ` prefix followed by your API key
154+
- Verify the API key has not been revoked or regenerated in PostHog
155+
- Alternatively, you can pass the token as a query parameter by using `https://us.i.posthog.com/i/v1/logs?token=<your-project-api-key>` as your endpoint
156+
157+
## Related resources
158+
159+
- [PostHog Logs documentation](https://posthog.com/docs/logs)
160+
- [PostHog Getting Started with Logs](https://posthog.com/docs/logs/start-here)
161+
- [OpenTelemetry Logs specification](https://opentelemetry.io/docs/specs/otel/logs/)

0 commit comments

Comments
 (0)