# Send an instance's errors to PostHog (/run/send-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`](/run/telemetry#see-a-fault) 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 [#turn-on-error-reports]

### Send the host and the token [#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.

```bash
marfa config update --file -
```

```json
{
  "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 [#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 [#what-the-host-must-be]

The token travels with every report, so the server holds the host to these rules:

* **An `https` address,** or an `http` address on the same machine, with no user name or password. Any other host is refused `400 validation_error`, naming `posthog_host` without 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_addresses`](/run/settings#let-webhooks-reach-a-private-network) turned 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](https://posthog.com/docs/api/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 [#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](/run/telemetry#send-traces-logs-and-metrics), 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 [#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.

```bash
marfa config set error_reporting_enabled false
```

`telemetry_enabled` set to `false` stops them too, with traces, logs and metrics. To stop for good, remove both settings in one change:

```bash
marfa config update --body '{"posthog_host": null, "posthog_project_token": null}'
```

The rules behind this page are in the [telemetry](https://github.com/withmarfa/marfa/blob/main/conformance/spec/instance.md#telemetry) section of the instance chapter of the contract.
