Skip to main content
When your agent already reports to Langfuse, Apgar can read the traces from there. The worker pulls observations from the Langfuse public API, so nothing changes in the agent.

​
Supported servers

The connector works with Langfuse Cloud and with self hosted Langfuse v4.

​
Add a connection

In Settings, Connections, add a Langfuse connection: Apgar authenticates with HTTP Basic (public_key:secret_key) and reads the project id from GET /api/public/projects, taking the first project the keys can see. Use Test to check the keys. A connection that an agent uses cannot be deleted until that agent is changed or deleted. fetch_content lets Apgar read observation input and output. The output is reduced to its length and JSON validity, tool inputs to a keyed hash of the arguments, and neither is stored. Set it to false if you do not want content to leave Langfuse. Output length still works from token counts, but Format failure rate, Retry rate, and Loop rate are then unavailable.

​
Add an agent

Choose Add agent with the Langfuse source, pick the connection, and describe which traces belong to the agent: A filter needs at least a trace name, a tag, or a metadata pair. One project can feed several agents. When two filters match the same trace, the agent created first owns it, and apgar_langfuse_filter_overlap_total counts the overlap.
The Langfuse Python SDK v4 and JS SDK v5 export only their own spans, spans that carry a gen_ai.* attribute, and spans from known LLM instrumentation scopes. Tool and agent spans from other instrumentation never reach Langfuse, so Apgar cannot see their errors, retries, and loops. Pass a permissive should_export_span (shouldExportSpan in JS) to the SDK if your tool spans are filtered out.

​
Release, environment, and session

The connector maps Langfuse fields onto the same attributes the OTLP path uses: Set the release on every trace, for example from your deploy pipeline. A trace without a release is stored as untagged and is never evaluated. A prompt version change inside one release shows up as a Prompt version slice; it does not open a new release by itself. Set the agent’s Release attribute to langfuse.release to read the trace release, or to langfuse.trace.metadata.<key> to read a metadata key, for example langfuse.trace.metadata.version for the key version. Apgar reads Langfuse traces only through their Langfuse fields, so apgar.release, gen_ai.agent.version, or service.version leave every turn untagged. The agent’s Environment works as it does for OTLP: only turns whose Langfuse environment equals it create releases and count in comparisons. Add agent fills in production. Set it to the environment your traces carry, default when the SDK sets none, or clear it to accept every environment. To read the surface from Langfuse, set Surface attribute to metadata.<key> for a metadata key, or tag:<prefix> to use the rest of the first tag that starts with the prefix. See Attribute reference.

​
Sync cycle

The worker runs one sync cycle per connection every 60 seconds (APGAR_LANGFUSE_SYNC_INTERVAL_SECONDS):
  1. The window runs from the watermark minus a 30 minute lookback to 2 minutes before now. The first successful cycle of a connection starts 24 hours back. It runs within a minute of saving the connection, even before an agent uses it, so an agent added later sees traces from about 30 minutes before it was added on.
  2. Phase one lists the root observations in the window that match each agent filter.
  3. Phase two loads the remaining observations of those traces in batches of 50 trace ids, over a window widened by one hour on each side so that late children are found.
  4. The watermark moves forward only after the whole window has been read.
A request that fails with 429, a 5xx status, or a network error is retried up to 8 times, waiting min(60, 2^attempt) seconds plus up to one second of jitter. A numeric Retry-After header replaces the computed wait. After the eighth failure the cycle fails and the watermark stays put, so the next cycle re-reads the same window. A failing connection does not hold back other connections. The sync status is shown on the agent page. The lookback covers observations that become visible late. Langfuse delays data from exporters that do not send x-langfuse-ingestion-version: 4, and from SDKs older than Python 4.7.0 or JS 5.4.0, by up to 15 minutes. Self hosted v4 can set LANGFUSE_MIGRATION_V4_NATIVE_OTEL_BEHAVIOUR=direct to remove that delay.

​
Trace ids

A Langfuse trace id of 32 hex characters is kept, lowercased. Any other id is replaced with the first 32 hex characters of its SHA-256, and the original stays on the span attribute langfuse.trace.id. Observation ids follow the same rule with 16 characters. Apgar stores no links into Langfuse; search the trace id there to open a trace.

​
Export from the Langfuse SDKs instead

The Langfuse Python SDK v4 and JS SDK v5 are built on OpenTelemetry, so the same tracer provider can also export to Apgar directly while it reports to Langfuse. Add an OTLP/HTTP exporter for Apgar as described in OpenTelemetry. The Langfuse export filter applies to the Langfuse span processor only; a second exporter on the same provider receives every span.