Skip to main content

Log streams and PostHog

Send call events and Convex logs to PostHog, find a failed call by its request ID, and follow work across scheduled jobs.

A Convex log stream sends every log record of a deployment to a log service. With call events turned on, you can then answer, after the fact, who ran which action in which tenant, and why it failed. This page uses PostHog Logs. Other log services work the same way, but their search differs.

What the stream sends

RecordContent
Call event (console topic)One line for each call with observe: true (a query only when it fails): action, actor, tenant, outcome, code and trace.
Function executionConvex's own record for each call: function path, duration, status, request ID, and the error text with its stack trace.
Console linesEvery console.log of your Convex functions, as it was written.

The call event and Convex's record of the same call have the same request ID.

Before you start

  • Use the Convex Pro plan. Log streams are not available on the free plan.
  • Turn on call events: defineFunctions({ …, observe: true }).
  • Create a PostHog project in the region of your users' data, for example PostHog EU Cloud for users in the EU.
The stream copies error texts and console lines to PostHog as they are. Before you connect it, check that your error messages and console.log calls do not contain values that a person typed, such as names, amounts or email addresses. Put such values in neither fail() messages nor why and fix. Write IDs.

Connect PostHog Logs

  1. In PostHog, open Settings > Project > General and copy the project token. It starts with phc_.
  2. In the Convex dashboard, open the deployment, then Settings > Integrations.
  3. Add PostHog Logs.
  4. Paste the project token.
  5. Set Host to the host of your PostHog region, for example https://eu.i.posthog.com. Without a host, Convex sends to the US region.
  6. Set Service name to a name for this deployment, for example myapp-prod. Use a different name for each deployment.
  7. Under Topics, select console and function_execution. Leave the other topics off until you need them.
  8. Save. Convex sends a verification record to PostHog.

The PostHog Error Tracking integration is a separate integration. It sends each failed call as an exception, with the full error text. Add it if you want failures grouped as issues.

Find a call

Open Logs in PostHog. Filter on the service.name resource attribute to see one deployment. Then use the Message filter with contains:

To findMessage contains
One call that a user reportedThe request ID that the user quoted, for example c80d6e0f0e0198a1
All call eventsbetter-convex.call
Refused callsbetter-convex.call, and in a second filter FORBIDDEN
Everything one call startedThe trace of its event, for example 5123956460443c3b
Everything one agent didThe agent's key, for example mcp:k57…:claude-desktop
Calls of revoked agentsbetter-convex.call, and in a second filter AGENT_DISABLED

A search for a request ID shows the call event and Convex's record of the same call. The call event says who acted and with which code. Convex's record has the duration, the final status and the error text.

A search for an agent's key finds its tool calls, where it is the actor, and the decisions of people on its requests, where it is the agent.

A search for a trace shows the events of each call in the chain: the call itself and the internal operations, internal actions and jobs it scheduled or ran, also those that ran hours later. Convex gives each scheduled call a new request ID, so only the trace connects them.

To see the calls of one function, filter on the convex.function.path attribute, for example clients:create.

Search for a word, a code or an ID, not for a part of the JSON line such as "code":"FORBIDDEN". PostHog stores Convex's record as the message, and the call event is a quoted string inside it, so each quotation mark of the call event has a backslash before it.

Each field of a call event is text in the message, not an attribute of its own. You can filter by words and IDs, but you cannot group or count by actor or code in the filter bar.

Get an alert

Save a filter as a view, for example better-convex.call and FORBIDDEN. Add a PostHog alert on that view to get a message when the number of matching lines goes over a limit. A sudden rise in refused calls can show a broken client or someone who tries to read data of other tenants. A rise in AGENT_DISABLED or RATE_LIMITED can show a stolen agent token that is still in use.

Protect the logs

Call events contain user IDs and tenant IDs. Under the GDPR, these are personal data, even without a name.

  • Sign a data processing agreement with PostHog.
  • Check how long your PostHog plan keeps logs, and keep them no longer than you need.
  • Give access to the PostHog project only to the people who need it. They see the activity of every user in every tenant.
  • Set a volume limit or a billing limit in PostHog. Anyone can make queries fail, and failed queries write call events without a rate limit.

The project token can only send data, but anyone who has it can send false records. Use the logs to find problems. Use the audit log in your own database as the record of who changed which rows.