> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tai42.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Langfuse monitoring

> Send traces, generations, and costs to a Langfuse project — cloud or self-hosted.

`tai42-monitoring-langfuse` implements the
[monitoring backend](/guides/authors/monitoring-backend) contract against
[Langfuse](https://langfuse.com). With it selected, tool runs and agent turns
write traces to a Langfuse project, and the [Studio](/studio) reads them back
through the same interface.

## Install and select it

```bash theme={null}
pip install tai42-monitoring-langfuse
```

```yaml manifest.yml theme={null}
monitoring_module: tai42_monitoring_langfuse
```

## Configure the project

Create a project in Langfuse Cloud or in a self-hosted instance and copy its key
pair from the project settings.

```bash theme={null}
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://cloud.langfuse.com
LANGFUSE_TRACING_ENVIRONMENT=tai
```

| Variable                       | Default | Effect                                                                              |
| ------------------------------ | ------- | ----------------------------------------------------------------------------------- |
| `LANGFUSE_PUBLIC_KEY`          | unset   | Project public key. Required.                                                       |
| `LANGFUSE_SECRET_KEY`          | unset   | Project secret key. Required.                                                       |
| `LANGFUSE_HOST`                | unset   | Langfuse base URL — the cloud endpoint or your own instance. Required.              |
| `LANGFUSE_TIMEOUT_SECONDS`     | `30`    | Client timeout, applied per read request too.                                       |
| `LANGFUSE_TRACING_ENVIRONMENT` | `tai`   | Langfuse `environment` stamped on every write, and the scope every read filters by. |

<Warning>
  Selecting `monitoring_module` without the three required keys raises at startup,
  naming all three. That is deliberate: a monitoring backend that silently drops
  traces is worse than a server that will not boot. To run without monitoring, omit
  `monitoring_module` entirely — the runtime falls back to a built-in no-op.
</Warning>

## Share one project between deployments

`LANGFUSE_TRACING_ENVIRONMENT` both stamps writes and scopes reads, so several
deployments can share a single Langfuse project by diverging on it — staging and
production write into the same project and each reads only its own traces.

Reading a trace by id is the one unscoped call, because trace ids are globally
unique.

## Self-hosted Langfuse

The [`tai-distribution`](https://github.com/tai42ai/tai-distribution) repo ships a
separate Compose stack under `compose/langfuse/` that brings up Langfuse with its
own Postgres, ClickHouse, Redis, and object store. It is a standalone stack: wire
the runtime to it with the four variables above.

<Note>
  The package pins the Langfuse SDK to a narrow range because it reaches into SDK
  internals for the read paths. Upgrading Langfuse's server is safe; changing the
  pinned SDK is not.
</Note>

## See also

* [Observe](/operate/observe) — metrics, traces, and what the runtime emits.
* [Author a monitoring backend](/guides/authors/monitoring-backend) — the contract.