Skip to main content
Monitoring plugin · listing tai42/monitoring-langfuse

​
Install

​
Permissions

​
Provides

​
langfuse

Monitoring — Langfuse monitoring backend — trace/span emission and the observability read surface. The Langfuse monitoring backend records tool-run and agent-turn traces into a Langfuse project — cloud or self-hosted — and the Studio reads them back through the same interface. Records are written by the platform’s OpenTelemetry writer: each process exports OTLP to an OpenTelemetry collector running as its own container, and the collector maps the platform’s attribute names onto Langfuse’s and sends them to Langfuse’s OTLP endpoint. Reads go to Langfuse’s public REST API (Observations v2 and Metrics v2) over HTTP, authenticated with the project’s key pair.

​
Enable it

manifest.yml

​
Configuration

​
The reader: the LANGFUSE_ env group

Create a project in Langfuse Cloud or a self-hosted instance and copy its key pair from the project settings. These five are the only LANGFUSE_* names the backend reads, and the plugin owns the LANGFUSE_ prefix: any other LANGFUSE_* name — the Langfuse SDK’s own export and debug settings (LANGFUSE_FLUSH_AT, LANGFUSE_FLUSH_INTERVAL, LANGFUSE_OTEL_TRACES_EXPORT_PATH, LANGFUSE_MEDIA_UPLOAD_ENABLED, LANGFUSE_DEBUG) or a mistyped name — refuses boot and every env write with an error naming it. The export is tuned through the OTEL_* environment below and the collector.

​
The writer: the standard OpenTelemetry environment

OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT and OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT have no effect: the writer never truncates a recorded value.

​
The collector

The collector holds the backend credential, named outside the LANGFUSE_ prefix: OTEL_COLLECTOR_LANGFUSE_AUTH is the base64 of public_key:secret_key, sent as Authorization: Basic … to ${LANGFUSE_HOST}/api/public/otel, together with the header x-langfuse-ingestion-version: 4, which marks the batches as Langfuse 4 ingestion (a Langfuse that still writes both its old and new tables delays unmarked data on its reads by up to about 10 minutes). Its pipeline maps the platform’s tai42.trace.*, tai42.run.version, tai42.level, tai42.status_message, tai42.span.kind and tai42.usage.cost_usd attributes onto Langfuse’s names; GenAI messages, tool arguments and results, and chain inputs and outputs use the OpenTelemetry names Langfuse reads natively. Its sending queue lives on a volume and retries until delivered.
Selecting monitoring_module without the three required LANGFUSE_* keys, without an OTLP endpoint, or without OTEL_PYTHON_SDK_INTERNAL_METRICS_ENABLED=true raises at startup, naming what is missing — 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.

​
Share one project between deployments

LANGFUSE_TRACING_ENVIRONMENT both stamps records and scopes reads, so several deployments can share one Langfuse project by diverging on it — staging and production write into the same project and each reads only its own traces. Reading a trace or an observation by id is unscoped, because ids are globally unique.

​
Run attribution and data retention

The platform tags each run’s trace with generic identity at its shared chokepoints, and the collector maps them onto Langfuse’s native trace dimensions: user_id, session_id, version, and tags — so runs are filterable and groupable by exactly those, including from the observability user / session / meta.<key> query params. user_id is person-id-first: a run with a resolved person is attributed by that person’s stable person_id. With no person it falls back to the raw {channel}:{client_address} the door saw (an end-user address), or, on the API door where no channel exists, the bare client_address. Treat these as personal data.
That identity lands in your Langfuse project, so it is yours to govern. Set a deliberate retention policy — Langfuse keeps traces until you delete them; the platform sets none on your behalf. Honour erasure by deleting a subject’s traces keyed on their user_id (the person_id, or the raw address for an unlinked subject); person-id-first keeps a linked subject’s cross-channel history under one deletable key.

​
What the reader serves

A run is one trace with one root observation: the run’s start is its root’s start, and its latency is its root’s duration. On the runs list every sort combines with every filter, within these bounds:
  1. Newest first with only the name, user, session, version, tags, metadata and latency filters: paged up to run 5,000.
  2. Cost or tokens, highest first, with only the name and tags filters: ranked by Langfuse over the whole time range, paged up to run 1,000.
  3. Every other read (a latency, name or run id sort, any ascending sort, a cost or tokens sort with a user, session, version, metadata or latency filter, or a cost, token, status or model filter with any sort) is ranked by the plugin over the runs that started in the time range. It is served when the range holds at most 2,000 matching runs and, when the read needs every observation of every run, at most 50,000 observations.
A read past a bound answers that it is too broad and names the bound; narrow the time range or add filters. The Studio always sends a time range (the last 30 days by default).

​
Quirks

  • The plugin reads Langfuse’s Observations v2 and Metrics v2 REST endpoints, which need a Langfuse server 4.59.0 or newer — Langfuse Cloud, or a self-hosted 4.x stack.
  • A read answered 408, 429 or 5xx is retried up to twice (after the answer’s Retry-After, at most 60 s, or a 1 s / 2 s backoff); any other failed read, a timeout included, answers with an error naming the request.
  • A self-hosted Langfuse is a standalone stack (its own Postgres, ClickHouse, Redis, and object store); the collector and the reader both reach it at LANGFUSE_HOST.

​
See also

  • Observe — metrics, traces, the collector, and what the runtime emits.