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
| Record | Content |
|---|---|
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 execution | Convex's own record for each call: function path, duration, status, request ID, and the error text with its stack trace. |
| Console lines | Every 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.
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
- In PostHog, open Settings > Project > General and copy the project
token. It starts with
phc_. - In the Convex dashboard, open the deployment, then Settings > Integrations.
- Add PostHog Logs.
- Paste the project token.
- 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. - Set Service name to a name for this deployment, for example
myapp-prod. Use a different name for each deployment. - Under Topics, select
consoleandfunction_execution. Leave the other topics off until you need them. - 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 find | Message contains |
|---|---|
| One call that a user reported | The request ID that the user quoted, for example c80d6e0f0e0198a1 |
| All call events | better-convex.call |
| Refused calls | better-convex.call, and in a second filter FORBIDDEN |
| Everything one call started | The trace of its event, for example 5123956460443c3b |
| Everything one agent did | The agent's key, for example mcp:k57…:claude-desktop |
| Calls of revoked agents | better-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.