Send an instance's errors to PostHog
Have your instance report each error it couldn't handle to a PostHog project of your own, for PostHog's error tracking.
PostHog is an outside service with error tracking. Marfa doesn't need it, and an instance sends nothing to PostHog until you set both of its settings. Most owners never do: marfa attention lists each fault, and a webhook on attention.raised tells you of one as it happens.
You need a PostHog project, on PostHog Cloud or a PostHog you host, and its project token, which PostHog shows in the project's settings.
Turn on error reports
Send the host and the token
Both are secrets, and they're set together in one change. Send them on standard input, so the token stays out of your shell history: run this, paste the body, then press Control-D.
marfa config update --file -{
"posthog_host": "https://eu.i.posthog.com",
"posthog_project_token": "<project token>"
}Use your project's region: https://eu.i.posthog.com for EU Cloud and https://us.i.posthog.com for US Cloud. For a PostHog you host, use its own address.
Check that both are set
Run marfa config get. It lists both settings in secrets_set, and never shows their values. They take effect at once, with no restart, from the next error.
What the host must be
The token travels with every report, so the server holds the host to these rules:
- An
httpsaddress, or anhttpaddress on the same machine, with no user name or password. Any other host is refused400 validation_error, namingposthog_hostwithout repeating it. - Both settings or neither. A change that would leave one set without the other is refused, and nothing changes.
- A public address. A PostHog on the same machine or a private network, such as Tailscale, needs
allow_private_addressesturned on. While it's off, a host whose name leads to a private address receives nothing.
Marfa posts each batch of reports to PostHog's capture v1 endpoint, i/v1/analytics/events under the host, with the token as a bearer token. A PostHog you host receives reports only if its release serves that endpoint.
What a report holds
Marfa reports an error that no handler answered, which the request meets as a 500. The report holds the error's kind, its message and stack, the request's ID, the method, the path and the error code. It also names the instance by service.instance.id, once the database has opened, and its release by service.version, with any attributes you set in otel_resource_attributes.
A connector whose last run failed is reported too, as one report of type ConnectorRunFailed that names no connector, item or error.
When the instance exports traces, each report carries $trace_id and $span_id, so PostHog leads you to the trace of the request that failed. A report attaches no person, and turns off PostHog's location lookup.
Pause or stop the reports
error_reporting_enabled set to false pauses the reports. Turning it back on is refused unless both PostHog settings are set.
marfa config set error_reporting_enabled falsetelemetry_enabled set to false stops them too, with traces, logs and metrics. To stop for good, remove both settings in one change:
marfa config update --body '{"posthog_host": null, "posthog_project_token": null}'The rules behind this page are in the telemetry section of the instance chapter of the contract.