---
title: "PostHog"
description: "Use Blyp's PostHog connector for automatic log forwarding, manual logger APIs, and server-side error tracking."
canonical_url: "https://www.blyp.dev/docs/connectors/posthog"
markdown_url: "https://www.blyp.dev/docs/connectors/posthog.md"
last_updated: "2018-10-20"
x_farming_labs_generated_preamble: true
agent:
  task: "Forward Blyp server logs to PostHog Logs and optionally promote exceptions to Error Tracking."
  outcome: "A test record appears in PostHog Logs and an opted-in exception appears in Error Tracking."
  appliesTo:
    package:
      - "@blyp/core"
      - "posthog-node"
  prerequisites:
    - "A PostHog project key and host are available."
  files:
    - "blyp.config.ts"
    - ".env"
  commands:
    - "pnpm add @blyp/core posthog-node @opentelemetry/api-logs @opentelemetry/exporter-logs-otlp-http @opentelemetry/resources @opentelemetry/sdk-logs"
  sideEffects:
    - "Logs and selected exception metadata leave the application for PostHog."
  verification:
    - "Emit a unique log"
    - "flush Blyp"
    - "and find it in the configured PostHog project."
  rollback:
    - "Set connectors.posthog to false and remove unused peers."
  failureModes:
    - symptom: "Events appear but exceptions are absent from Error Tracking."
      resolution: "Enable the connector errorTracking option and use the documented exception capture path."
---

# PostHog
URL: /docs/connectors/posthog
LLM index: /llms.txt
Description: Use Blyp's PostHog connector for automatic log forwarding, manual logger APIs, and server-side error tracking.
Related: /docs/connectors, /docs/configuration, /docs/integrations/client

<!-- farming-labs:agent-contract:start -->
## Agent Contract

Task: Forward Blyp server logs to PostHog Logs and optionally promote exceptions to Error Tracking.
Outcome: A test record appears in PostHog Logs and an opted-in exception appears in Error Tracking.

### Applies To

- Package: `@blyp/core`, `posthog-node`

### Prerequisites

- A PostHog project key and host are available.

### Files

- `blyp.config.ts`
- `.env`

### Commands

- `pnpm add @blyp/core posthog-node @opentelemetry/api-logs @opentelemetry/exporter-logs-otlp-http @opentelemetry/resources @opentelemetry/sdk-logs`

### Side Effects

- Logs and selected exception metadata leave the application for PostHog.

### Verification

- Emit a unique log
- flush Blyp
- and find it in the configured PostHog project.

### Rollback

- Set connectors.posthog to false and remove unused peers.

### Failure Modes

- Events appear but exceptions are absent from Error Tracking. — Recovery: Enable the connector errorTracking option and use the documented exception capture path.
<!-- farming-labs:agent-contract:end -->

# PostHog

Configure the project key and host, emit a unique server record, and await flush before checking
PostHog Logs. Browser and Expo logs must traverse Blyp ingestion. Error Tracking is a separate opt-in;
ordinary forwarded logs do not automatically become exception issues.

Blyp's PostHog connector covers two related flows on server runtimes:

- log forwarding into PostHog Logs
- exception capture into PostHog Error Tracking

## Install required peer packages

Install the optional peer dependencies when this connector is enabled:

```bash
bun add posthog-node @opentelemetry/api-logs @opentelemetry/exporter-logs-otlp-http @opentelemetry/resources @opentelemetry/sdk-logs
```

## Config

Configure PostHog under `connectors.posthog`:

```ts
export default {
  connectors: {
    posthog: {
      enabled: true,
      mode: "auto",
      projectKey: process.env.POSTHOG_PROJECT_KEY,
      host: "https://us.i.posthog.com",
      serviceName: "api",
      errorTracking: {
        enabled: true,
        mode: "auto",
        enableExceptionAutocapture: true,
      },
    },
  },
};
```

## Config fields

- `enabled`: enables PostHog delivery
- `mode`: `auto` or `manual`
- `projectKey`: PostHog project API key
- `host`: defaults to `https://us.i.posthog.com`
- `serviceName`: defaults to `blyp-app`
- `errorTracking.enabled`: enables PostHog exception capture
- `errorTracking.mode`: `auto` or `manual`
- `errorTracking.enableExceptionAutocapture`: enables uncaught exception and unhandled rejection autocapture through `posthog-node`

## Automatic server forwarding

When `mode: "auto"` is enabled, normal Blyp server loggers forward into PostHog automatically.

When `errorTracking.mode: "auto"` is enabled, Blyp handled server errors can also be captured into PostHog Error Tracking.

> In `auto` mode, Blyp forwards each log line to PostHog with the log level, message, and structured fields preserved for querying and filtering.

## Manual APIs

Use `@blyp/core/posthog` when you want explicit control:

```ts
import {
  capturePosthogException,
  createPosthogErrorTracker,
  createPosthogLogger,
  createStructuredPosthogLogger,
} from "@blyp/core/posthog";

createPosthogLogger().info("manual posthog log");

createPosthogErrorTracker().capture(new Error("manual posthog exception"));

capturePosthogException(new Error("wrapped posthog exception"), {
  distinctId: "usr_123",
  properties: {
    feature: "checkout",
  },
});

const structured = createStructuredPosthogLogger("checkout", {
  orderId: "ord_123",
});

structured.info("manual start");
structured.emit({ status: 200 });
```

## Browser and Expo forwarding

Browser and Expo do not use `posthog-node` directly. They request forwarding through Blyp ingestion:

```ts
const logger = createClientLogger({
  endpoint: "/inngest",
  connector: "posthog",
});
```

```ts
const logger = createExpoLogger({
  endpoint: "https://api.example.com/inngest",
  connector: "posthog",
});
```

Client `error` and `critical` logs requested through the PostHog connector are promoted into PostHog exceptions only when server-side PostHog error tracking is enabled in `auto` mode.

## Notes

- PostHog direct delivery is for Node/Bun server runtimes
- Convex maps `connectors.posthog` to PostHog Logs OTLP (`https://us.i.posthog.com/i/v1/logs`) from actions. Exception autocapture is ignored. See [Convex](/docs/integrations/convex).
- `connectors.delivery` can make retryable PostHog forwarding failures durable without Redis or another external queue
- browser and Expo still post to Blyp first
- Blyp warns once when the client or Expo app requests PostHog forwarding but the server connector is missing
- Workers remain out of scope for PostHog error tracking

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).