Convex

Convex runs your backend as short-lived isolates, so the usual posthog-node shutdown flow doesn't apply. This doc covers what does: capturing events and flags from Convex functions, matching frontend and backend events to the same person, tracing LLM calls, and syncing Convex tables into PostHog.

Get your PostHog project token

Every integration on this page needs the same two values:

• Project token - Starts with phc_. Found in PostHog under Settings > Project > General, labeled Project token.
• Host - https://us.i.posthog.com for PostHog US Cloud, https://eu.i.posthog.com for EU Cloud, or your own URL for self-hosted PostHog.

Capture events and flags from your Convex code

The @posthog/convex component captures events, identifies users, and forwards exceptions from mutations and actions. Local feature flags also work in queries.

Requires Convex 1.39 or newer.

1. Install the component

npm install @posthog/convex

yarn add @posthog/convex

pnpm add @posthog/convex

bun add @posthog/convex

Register it in convex/convex.config.ts and forward your credentials from the app down to the component:

// convex/convex.config.ts
import { defineApp } from "convex/server"
import { v } from "convex/values"
import posthog from "@posthog/convex/convex.config.js"

const app = defineApp({
    env: {
        POSTHOG_PROJECT_TOKEN: v.string(),
        POSTHOG_HOST: v.optional(v.string()),
        POSTHOG_PERSONAL_API_KEY: v.optional(v.string()),
        POSTHOG_FLAGS_POLLING_INTERVAL_SECONDS: v.optional(v.string()),
    },
})

app.use(posthog, {
    env: {
        POSTHOG_PROJECT_TOKEN: app.env.POSTHOG_PROJECT_TOKEN,
        POSTHOG_HOST: app.env.POSTHOG_HOST,
        POSTHOG_PERSONAL_API_KEY: app.env.POSTHOG_PERSONAL_API_KEY,
        POSTHOG_FLAGS_POLLING_INTERVAL_SECONDS: app.env.POSTHOG_FLAGS_POLLING_INTERVAL_SECONDS,
    },
})

export default app

Environment variables:

2. Set your PostHog credentials

npx convex env set POSTHOG_PROJECT_TOKEN <ph_project_token>
npx convex env set POSTHOG_HOST https://us.i.posthog.com

For local feature flag evaluation (covered in step 5), also set a secret API key:

npx convex env set POSTHOG_PERSONAL_API_KEY phs_your_secret_api_key

Local evaluation kicks in on the next cron tick — no redeploy needed.

3. Initialize the client

Create convex/posthog.ts. Other backend functions import the posthog instance from here. Credentials live on the component, so the constructor just needs the component reference:

// convex/posthog.ts
import { PostHog } from "@posthog/convex"
import { components } from "./_generated/api"

export const posthog = new PostHog(components.posthog)

4. Capture events and identify users

capture and identify work in mutations and actions. They schedule the PostHog API call via ctx.scheduler.runAfter, so they return immediately without blocking the caller.

// convex/users.ts
import { mutation } from "./_generated/server"
import { v } from "convex/values"
import { getAuthUserId } from "@convex-dev/auth/server"
import { posthog } from "./posthog"

export const updateProfile = mutation({
    args: { plan: v.string() },
    handler: async (ctx, args) => {
        const userId = await getAuthUserId(ctx)
        if (userId === null) throw new Error("Not authenticated")

        await ctx.db.patch(userId, { plan: args.plan })

        await posthog.identify(ctx, {
            distinctId: userId,
            properties: { plan: args.plan },
        })

        await posthog.capture(ctx, {
            distinctId: userId,
            event: "plan_changed",
            properties: { plan: args.plan },
        })
    },
})

Use the same Convex user ID as the distinctId everywhere so PostHog can stitch events from every source onto one person. See stitching frontend and backend below for the frontend setup.

5. Evaluate feature flags

@posthog/convex supports two flag evaluation paths:

• Local (getFeatureFlag, isFeatureEnabled, getFeatureFlagPayload, getAllFlags) runs against flag definitions cached on your Convex deployment. Works in queries, mutations, and actions. No per-call network request, and a query re-runs automatically when cached definitions refresh. Requires POSTHOG_PERSONAL_API_KEY. Use this when you can.
• Remote (evaluateFlag, evaluateFlagPayload, evaluateAllFlags) hits PostHog's /flags endpoint on every call. Action-only. Handles every flag, including the ones local can't, and needs no personal API key.

Local evaluation runs automatically once POSTHOG_PERSONAL_API_KEY is set. The component runs its own cron that refreshes flag definitions every minute, so you don't write your own. Tune the cadence with POSTHOG_FLAGS_POLLING_INTERVAL_SECONDS. If you call a local-eval method without the key configured, the client throws and points you at the remote evaluate* methods.

Read a flag from a query:

// convex/pricing.ts
import { query } from "./_generated/server"
import { v } from "convex/values"
import { posthog } from "./posthog"

export const getDiscount = query({
    args: { userId: v.string() },
    handler: async (ctx, args) => {
        const variant = await posthog.getFeatureFlag(ctx, {
            key: "discount-campaign",
            distinctId: args.userId,
        })

        if (variant === "variant-a") return { discount: 20 }
        if (variant === "variant-b") return { discount: 10 }
        return { discount: 0 }
    },
})

A React client subscribed to this query re-renders the next time the cron refreshes flag definitions, up to the configured interval (one minute by default).

To force a refresh between cron ticks (for example, right after creating a flag in development), call posthog.reloadFeatureFlags(ctx) from an action.

If you're running an experiment against a locally-evaluated flag, fire an exposure event yourself from a mutation or action, since local eval can't schedule capture from inside a query:

await posthog.capture(ctx, {
    event: "$feature_flag_called",
    distinctId: userId,
    properties: {
        $feature_flag: "discount-campaign",
        $feature_flag_response: variant,
        locally_evaluated: true,
    },
})

6. Capture exceptions with custom properties

If you want every uncaught exception forwarded to PostHog automatically without wrapping each call site, configure Convex's first-party PostHog Error Tracking destination in the Convex dashboard. Use captureException when you want to attach custom properties at a specific call site:

// convex/billing.ts
import { action } from "./_generated/server"
import { v } from "convex/values"
import { posthog } from "./posthog"

export const chargeCard = action({
    args: { userId: v.string(), amount: v.number() },
    handler: async (ctx, args) => {
        try {
            await callStripe(args.amount)
        } catch (error) {
            await posthog.captureException(ctx, {
                error,
                distinctId: args.userId,
                additionalProperties: { amount: args.amount },
            })
            throw error
        }
    },
})

Stitch frontend and backend events together

PostHog stitches frontend and backend events onto the same person when both sides use the same distinctId string.

Install posthog-js and @posthog/react in your frontend. The example below uses React, but any JavaScript framework PostHog supports works the same way: call posthog.identify() with the same string the backend uses as distinctId.

npm install posthog-js @posthog/react

yarn add posthog-js @posthog/react

pnpm add posthog-js @posthog/react

bun add posthog-js @posthog/react

Initialize PostHog at the root of your app, the same way you would in any React project:

// src/main.tsx
import { StrictMode } from "react"
import { createRoot } from "react-dom/client"
import posthog from "posthog-js"
import { PostHogProvider } from "@posthog/react"
import App from "./App"

posthog.init(import.meta.env.VITE_POSTHOG_PROJECT_TOKEN, {
    api_host: import.meta.env.VITE_POSTHOG_HOST,
})

createRoot(document.getElementById("root")!).render(
    <StrictMode>
        <PostHogProvider client={posthog}>
            <App />
        </PostHogProvider>
    </StrictMode>
)

Then, right after a user signs in via Convex Auth (or Clerk, Auth0, etc.), call identify on the frontend with the same Convex user ID your backend uses. The currentUser query referenced below is whatever Convex query exposes the authenticated user to your client (the Convex Auth docs cover defining it):

// src/components/AuthSync.tsx
import { useEffect } from "react"
import { useQuery } from "convex/react"
import { usePostHog } from "@posthog/react"
import { api } from "../../convex/_generated/api"

export function AuthSync() {
    const posthog = usePostHog()
    const me = useQuery(api.users.currentUser) // your own query

    useEffect(() => {
        if (me?._id) {
            posthog.identify(me._id, { email: me.email, name: me.name })
        }
    }, [me?._id, posthog])

    return null
}

Mount <AuthSync /> once near the root of your app, inside the <PostHogProvider> and below your Convex <Authenticated> boundary if you have one. The me?._id guard skips the identify call until authentication completes.

Matching IDs connect frontend and backend events for that person. Session links need an explicit session ID. Convex log streams and dashboard exception reporting use separate ID rules, described below.

npx convex env set VITE_POSTHOG_PROJECT_TOKEN <ph_project_token>
npx convex env set VITE_POSTHOG_HOST https://us.i.posthog.com

Pass session IDs to backend functions

Query, mutation, and action calls from the Convex client do not give your handler an HTTP request. Pass the browser IDs as function arguments when you need them. Read the session ID when you call the function, since it can change while the page is open:

await updateProfile({
    plan: "pro",
    sessionId: posthog.get_session_id(),
    distinctId: posthog.get_distinct_id(),
})

Use your existing browser PostHog instance and Convex mutation. Add optional string validators to that mutation, and resolve the authenticated person on the server:

import { mutation } from "./_generated/server"
import { v } from "convex/values"
import { posthog } from "./posthog"

function cleanId(value: string | undefined): string | undefined {
    const id = value?.trim()
    return id && id.length <= 1000 && !/[\x00-\x1f\x7f-\x9f]/.test(id) ? id : undefined
}

export const updateProfile = mutation({
    args: {
        plan: v.string(),
        sessionId: v.optional(v.string()),
        distinctId: v.optional(v.string()),
    },
    handler: async (ctx, args) => {
        const identity = await ctx.auth.getUserIdentity()
        const distinctId = identity?.tokenIdentifier ?? cleanId(args.distinctId)
        if (!distinctId) throw new Error("Missing analytics identity")
        const sessionId = cleanId(args.sessionId)

        await posthog.capture(ctx, {
            distinctId,
            event: "plan_changed",
            properties: {
                plan: args.plan,
                ...(sessionId ? { $session_id: sessionId } : {}),
            },
        })
    },
})

Add this capture to your existing authorized profile update. This example uses the authenticated tokenIdentifier. If your app uses its own user ID, resolve that ID on the server and use the same string with posthog.identify() in the browser. The component's optional identify callback also takes priority over a supplied distinctId.

Browser IDs are analytics hints. Use Convex authentication and authorization to control access to data. Missing or invalid session IDs stay absent; the server does not create browser sessions.

@posthog/convex copies event properties into the scheduled capture call. Mutation scheduling commits with the mutation: if the mutation throws, its scheduled capture is rolled back too. Queries cannot schedule captures. Scheduled application functions do not inherit authentication or ambient context. Pass the selected IDs as arguments to an internal scheduled function when it needs them, and keep authorization checks at the public entry point.

Application spans and logs

@posthog/convex does not install an OpenTelemetry provider or attach IDs to function spans. For application-created spans, use sessionId and posthogDistinctId as span attributes. Keep explicit application attributes when you add these defaults:

const span = tracer.startSpan("update_profile", {
    attributes: {
        ...(sessionId ? { sessionId } : {}),
        posthogDistinctId: distinctId,
        ...applicationAttributes,
    },
})

Apply the IDs to each span that needs them. If a Node action already uses posthog-node and an application-owned OpenTelemetry provider, the Node span processor can apply the IDs inside withContext(). Keep those Node imports in a file with "use node". The full Node SDK cannot be bundled into queries or mutations. The default Convex runtime supports AsyncLocalStorage, but its values do not cross ctx.runQuery, ctx.runMutation, or ctx.runAction calls. Pass IDs explicitly across these boundaries. Await action work and exporter flushes before the action returns.

Convex's PostHog log stream sends function metadata and console output in the OTLP log body. IDs you print in console output remain body content; this does not establish canonical log attributes or trace links. The dashboard's PostHog exception destination uses the authenticated tokenIdentifier, or the deployment name when unauthenticated. It does not document a browser session ID. Use the component's captureException() with an explicit distinctId and $session_id in additionalProperties when you need that session link on a specific exception.

Trace LLM calls and Convex Agent

If your app calls LLM providers from Convex actions, or uses @convex-dev/agent, forward the traces to PostHog AI observability to capture generations, traces, spans, token counts, latency, and cost per model call.

Setup uses @posthog/ai and OpenTelemetry rather than the @posthog/convex component. The full installation steps live on the Convex AI observability installation page, covering both vanilla Vercel AI SDK or OpenAI calls and experimental_telemetry on @convex-dev/agent.

Sync Convex tables into PostHog

If you want to query Convex data alongside event data, use the Convex data warehouse source to stream your tables into PostHog's warehouse. You can then query them with SQL, join them to event data, and build insights over the union.

Requires a Convex Professional plan for Convex's streaming export API.

Further reading

• @posthog/convex README
• Convex AI observability installation
• Convex data warehouse source
• Convex PostHog log streams
• Convex PostHog exception reporting