PostHog Adapter

PostHog is an open-source product analytics platform. The evlog PostHog adapter sends your wide events as PostHog events, letting you query server-side logs alongside your product analytics, session replays, and feature flags.

Installation

The PostHog adapter comes bundled with evlog:

import { createPostHogDrain } from 'evlog/posthog'

Quick Start

1. Get your PostHog project API key

1. Log in to your PostHog dashboard
2. Go to Settings > Project > Project API Key
3. Copy the key (starts with phc_)

2. Set environment variables

NUXT_POSTHOG_API_KEY=phc_your-project-api-key

3. Create the drain plugin

import { createPostHogDrain } from 'evlog/posthog'

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

That's it! Your wide events will now appear in PostHog as evlog_wide_event events.

Configuration

The adapter reads configuration from multiple sources (highest priority first):

1. Overrides passed to createPostHogDrain()
2. Runtime config at runtimeConfig.evlog.posthog
3. Runtime config at runtimeConfig.posthog
4. Environment variables (NUXT_POSTHOG_* or POSTHOG_*)

Environment Variables

You can also use POSTHOG_API_KEY and POSTHOG_HOST as fallbacks.

Runtime Config

Configure via nuxt.config.ts for type-safe configuration:

export default defineNuxtConfig({
  runtimeConfig: {
    posthog: {
      apiKey: '', // Set via NUXT_POSTHOG_API_KEY
      host: '', // Set via NUXT_POSTHOG_HOST
    },
  },
})

Override Options

Pass options directly to override any configuration:

import { createPostHogDrain } from 'evlog/posthog'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('evlog:drain', createPostHogDrain({
    eventName: 'server_request',
    distinctId: 'my-backend-service',
    timeout: 10000,
  }))
})

Full Configuration Reference

Regions

PostHog offers US and EU cloud hosting. Set the host to match your region:

# EU region
NUXT_POSTHOG_API_KEY=phc_xxx
NUXT_POSTHOG_HOST=https://eu.i.posthog.com

Event Format

evlog maps wide events to PostHog events:

The event name defaults to evlog_wide_event but can be customized via the eventName option.

Custom Event Name

Use a custom event name to differentiate log types in PostHog:

import { createPostHogDrain } from 'evlog/posthog'

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

Custom Distinct ID

The distinct_id follows a fallback chain:

1. config.distinctId — explicit override in createPostHogDrain()
2. event.userId — automatically picked up if present as a string
3. event.service — final fallback

This means if you use setIdentity({ userId: 'usr_123' }) on the client, the userId flows through client transport → server ingest → PostHog drain, and is automatically used as distinct_id. No additional configuration needed.

// Client-side — identity is set once (e.g. after login)
setIdentity({ userId: 'usr_123' })

// Every log now includes userId
log.info({ action: 'checkout' })
// → PostHog event with distinct_id: 'usr_123'

To override distinct_id for all events regardless of userId, pass distinctId to the drain:

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('evlog:drain', createPostHogDrain({
    distinctId: 'my-backend-service', // Always uses this value
  }))
})

Querying Logs in PostHog

Once your events are flowing, you can query them in PostHog:

1. Go to Events and filter by evlog_wide_event
2. Use Insights to build dashboards on your wide event properties
3. Create Cohorts based on server-side behavior (e.g., users who triggered errors)

Example queries you can build:

• Error rate by endpoint (properties.path, properties.level = error)
• Slow requests over time (properties.duration > 1000)
• Request volume by service (properties.service)

Troubleshooting

Missing apiKey error

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

Make sure your environment variable is set and the server was restarted after adding it.

Events not appearing

PostHog processes events asynchronously. There may be a short delay (typically under 1 minute) before events appear in the dashboard.

1. Check the server console for [evlog/posthog] error messages
2. Verify your API key is correct and starts with phc_
3. Confirm your host matches your PostHog region (US vs EU)

Wrong region

If you're on PostHog EU but using the default US host, event delivery will fail and the adapter will log errors (for example under [evlog/posthog]) to your server console. Set the correct host:

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

Direct API Usage

For advanced use cases, you can use the lower-level functions:

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

// Send a single event
await sendToPostHog(event, {
  apiKey: 'phc_xxx',
})

// Send multiple events in one request
await sendBatchToPostHog(events, {
  apiKey: 'phc_xxx',
})

// Convert event to PostHog format (for inspection)
const posthogEvent = toPostHogEvent(event, { apiKey: 'phc_xxx' })

PostHog Logs (OTLP)

PostHog has a dedicated Logs product that accepts logs via the standard OTLP format. Instead of sending events to the PostHog Events pipeline, createPostHogLogsDrain() sends structured OTLP logs directly to PostHog Logs.

Why use PostHog Logs?

• Purpose-built UI — PostHog Logs provides a dedicated log viewer with filtering, search, and tail mode
• OTLP standard — Uses the OpenTelemetry log format, so your logs include severity levels, trace context, and structured attributes
• Same API key — Authenticates with your existing PostHog project API key

Quick Start

import { createPostHogLogsDrain } from 'evlog/posthog'

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

Configuration

createPostHogLogsDrain() uses the same configuration resolution chain as createPostHogDrain():

import { createPostHogLogsDrain } from 'evlog/posthog'

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('evlog:drain', createPostHogLogsDrain({
    apiKey: 'phc_...',
    host: 'https://eu.i.posthog.com', // EU region
  }))
})

How It Works

Under the hood, createPostHogLogsDrain() wraps the OTLP adapter's sendBatchToOTLP() with PostHog-specific defaults:

• Endpoint: {host}/i/v1/logs (PostHog's OTLP log ingest endpoint)
• Auth: Authorization: Bearer {apiKey} header
• Format: Standard OTLP ExportLogsServiceRequest with severity levels, trace context, and structured attributes

Events vs Logs

You can use both drains simultaneously to get the best of both worlds:

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

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

Next Steps

• Axiom Adapter - Send logs to Axiom
• OTLP Adapter - Send logs via OpenTelemetry Protocol
• Custom Adapters - Build your own adapter
• Best Practices - Security and production tips