Langfuse — LLM Engineering

Platform 10 of 12·OS Layer 10 (Observability Layer)·Required in all deployment modes

Scope of this page. Reference material for the Langfuse platform: what it is, what it is normally used for, and how and why Synedrix OS uses it. It is descriptive, not normative — where this page and a canonical spec in docs/os/ disagree, the canonical spec wins. Platform responsibilities are set by Tech Stack §9; the decision to run Langfuse rather than LangSmith is ADR-OS-001.

What Langfuse is link

Langfuse describes itself as “an open-source AI engineering platform that helps teams collaboratively debug, analyze, and iterate on their LLM applications.”

It is a self-hostable platform with four product surfaces built on one data model: observability (tracing), prompt management, evaluation, and metrics. The data model is the part worth reading closely, because nested trace debugging is one of the responsibilities the OS assigns to this layer.

The tracing data model link

Nesting lives entirely in the observation tree. Trace-level attributes — user_id, session_id, tags, metadata, version, release — “live on every observation within the trace”; Langfuse stores “one observations table, and each row holds the observation-level data plus a copy of the trace-level attributes.” Filtering and aggregation increasingly operate across observations rather than only at the trace level, which is why those attributes must be propagated to every span, not only the root.

Observations are typed. The available types are event (“the basic building block … used to track discrete events in a trace”), span (“durations of units of work in a trace”), generation (“logs generations of AI models incl. prompts, token usage and costs”), plus agent, tool, chain, retriever, evaluator, embedding and guardrail. Framework integrations set the type automatically; it can also be set explicitly through the SDKs. Only generation and embedding observations carry usage and cost.

Prompts, evaluation and scores link

Prompts are versioned and labelled; retrieval adds no latency because “prompts are cached client-side by the SDK.” Evaluation is split into offline (“test your application against a fixed dataset before you deploy”) and online (“scores live traces to catch issues in real traffic”). The evaluation methods that produce scores are LLM-as-a-Judge, code evaluators (custom Python or TypeScript), scores via UI, annotation queues for structured human review, and scores via API/SDK.

The ingestion path link

Langfuse “is built on OpenTelemetry, an open standard for collecting telemetry data from applications.” Three consequences matter architecturally:

• Anything that speaks OTLP can emit to it. Langfuse “can receive traces on the /api/public/otel (OTLP) endpoint,” authenticated with Basic Auth, over HTTP/JSON or HTTP/protobuf — gRPC is not supported.
• Received OTel spans are mapped onto the Langfuse data model. The langfuse.* attribute namespace maps directly and “always take[s] precedence over the generic OpenTelemetry conventions”; gen_ai.* and OpenInference attributes are also parsed.
• Ingestion is asynchronous and non-blocking: “Langfuse batches traces locally and sends them in the background.” Short-lived processes “must explicitly call flush() before exiting.”

Token and cost data is either ingested from the provider response or inferred “based on the model parameter of the generation at the time of ingestion,” against Langfuse’s predefined model definitions or against custom model definitions you add yourself.

What Langfuse is normally used for link

The cases Langfuse’s own documentation leads with:

• Debugging non-deterministic applications — “Because AI is inherently non-deterministic, debugging your application without any observability tool is more like guesswork.” Traces are “structured logs of every request that capture the exact prompt sent, the model’s response, token usage, latency, and any tools or retrieval steps in between.”
• Cost and usage attribution — per-generation token and USD cost, rolled up into dashboards, alerts, and the Metrics API.
• Decoupling prompt changes from code deploys — “non-technical team members update them directly in the UI while your application automatically fetches the latest version.”
• Testing a change before shipping it — datasets plus experiments, including as a CI/CD gate to “block deploys on regressions.”
• Scoring live production traffic — LLM-as-a-Judge and code evaluators running online, with annotation queues supplying human ground truth.
• Monitoring quality over time — score analytics, custom dashboards, and threshold alerts.

The common thread is that Langfuse owns what the model did and how good it was — not what the business decided, and not whether the infrastructure is healthy.

How Synedrix OS uses it link

Langfuse is the LLM engineering platform of Synedrix OS and sits at Layer 10 (Observability Layer) of the twelve-layer taxonomy. It is required in all three deployment modes. In the Layered Truth Summary it holds the LLM eval / observability truth class.

flowchart LR
  n1([Langfuse]):::term
  subgraph What it owns
    n2[Prompt versioning]:::agent
    n3[LLM/agent trace capture]:::agent
    n4[Token and cost attribution]:::agent
    n5[Model-call latency and error visibility]:::agent
    n6[Evaluations and quality scoring]:::agent
    n7[Nested trace debugging]:::agent
  end
  n1 --> n2
  subgraph What it does not own
    n8[Workflow sequencing retries approval routing]:::warn
    n9[n8n]:::term
    n8 --> n9
    n10[Stateful cyclic multi-agent reasoning]:::warn
    n11[LangGraph]:::term
    n10 --> n11
    n12[Policy decisions]:::warn
    n13[Policy Guard]:::term
    n12 --> n13
    n14[Workflow and outcome lineage agent influence graphs]:::warn
    n15[Neo4j]:::term
    n14 --> n15
    n16[Behavioural and product analytics feature flags]:::warn
    n17[PostHog]:::term
    n16 --> n17
    n18[Infrastructure health service dashboards SLO alerting]:::warn
    n19[Grafana LGTM Stack]:::term
    n18 --> n19
  end
  n1 --> n8
  subgraph Why Langfuse
    n20[Adopting LangGraph did not force adopting LangSmith]:::term
    n21[It runs with no internet access]:::term
    n22[Self-hosted is the same product as hosted]:::term
    n23[OpenTelemetry ingestion keeps the layer substitutable]:::term
  end
  n1 --> n20

What it owns link

Per Tech Stack §9, Langfuse owns:

• Prompt versioning
• LLM/agent trace capture
• Token and cost attribution
• Model-call latency and error visibility
• Evaluations and quality scoring
• Nested trace debugging

Its access pattern is async write/read. In the Agent Evaluation Spec, Langfuse is the platform for the output quality dimension: it “answers model-level questions,” while PostHog answers product and workflow-level questions and Grafana answers infrastructure and SLO questions.

One observability plane across Layer 3 and Layer 4 link

This is the load-bearing integration point. After ADR-OS-001 split the Agent Runtime (Layer 4) out of Orchestration (Layer 3), agent reasoning happens in two places: simple acyclic agents may still run as n8n AI Agent nodes, while iterative, consensus, reflect-and-revise and hierarchical patterns run in LangGraph. Both emit to Langfuse.

Synedrix OS Tech Stack §13 states it directly: LangGraph and LangChain emit traces to Langfuse via OpenTelemetry or the native exporter — “the same Layer 10 platform used by n8n agents.” The LangGraph Runtime Implementation Guide makes it a compliance condition rather than a preference: an agent is non-compliant unless “traces export to Langfuse; no LangSmith dependency.”

The practical effect is that a single governed workflow — n8n trigger, policy gate, LangGraph reasoning step, outcome persistence — produces one correlated view of every model call it made, regardless of which engine made it. The Observability & Metrics Spec depends on this: retrieval, groundedness, cost and semantic-validation events “correlate 1:1 with a Langfuse trace span and MUST carry the same trace_id so a metric flag can be traced back to the exact LLM call that produced it.” Langfuse’s OTel attribute mapping is where the OS correlation identifiers land — langfuse.trace.metadata.* for the filterable top-level keys, langfuse.session.id and langfuse.user.id for the grouping attributes.

What it does not own link

Traces are not an audit trail. This boundary is not a technicality and must not be blurred. Lineage and audit are owned by the Audit & Lineage Agent (os-agt-008) — which is strictly read-only — over Neo4j and Supabase, with the full outcome record specified by the Outcome Spec. Langfuse owns LLM observability. The two are structurally different: observability data is sampled and retained on an operational schedule, while an audit trail must be complete and durable, and an audit trail with gaps in it is not an audit trail. A Langfuse trace is evidence of how a model call executed; the Outcome Envelope and its os.outcome.* events are the record of what the system decided. Academy chapter 07.8 covers this in full.

How it is operated link

Self-hosted Langfuse “consists of two application containers, storage components, and an optional LLM API/Gateway”: a Langfuse Web container serving the UI and APIs, and a Langfuse Worker processing events asynchronously. Its storage components are Postgres (transactional), ClickHouse (OLAP — “stores traces, observations, and scores”), Redis/Valkey (queue and cache), and S3/blob storage (raw events and multi-modal attachments). All infrastructure components “must run with their timezone set to UTC.”

Two operational notes follow from that, both parallel to the n8n case:

• Langfuse’s Postgres and Redis are not the OS’s Postgres and Redis. Langfuse ships its own instances of platforms the OS also runs at Layer 7. Langfuse’s are infrastructure internal to the observability platform; Supabase PG17 is canonical relational truth and Redis is the OS coordination bus. Collapsing them onto one logical database is a deliberate decision, not a default.
• Some features need an LLM endpoint. The Playground and LLM-as-a-Judge evaluators require an LLM API or gateway, which “can be deployed in the same VPC or peered with the VPC.” In Modes 2 and 3 that endpoint is the local inference layer (Ollama/vLLM), which exposes an OpenAI-compatible API — the same property that lets Langfuse trace local inference with no code change, per the Deployment Model Spec. Local and fine-tuned models need custom model definitions in Langfuse for cost inference to work, since they are not in the predefined list.

Open item — how n8n traces actually reach Langfuse. Langfuse’s documentation states plainly that “currently, there is no native n8n tracing integration.” What exists officially is a Langfuse node for prompt management inside n8n, plus documented workarounds: an LLM gateway that broadcasts traces, and community projects that ship n8n execution data over OTLP. The Layer 3 → Layer 10 path is therefore real but not first-party: it depends on n8n’s own OpenTelemetry support or a gateway in front of the model call, feeding Langfuse’s OTLP endpoint. Modes 2 and 3 rule out any hosted gateway, so an air-gapped deployment must standardise on the OTel path. This needs an explicit implementation decision; it is not resolved by this page.

Why Langfuse link

• It is the reason LangSmith is not in the stack. This is the most important argument on the page. ADR-OS-001 evaluated LangChain, LangGraph and LangSmith as three independent decisions and adopted the first two while rejecting the third. LangSmith is “proprietary commercial SaaS — violates Principle 11 (Open by default, sovereign by design)”; “self-hosting requires an enterprise licence — not OSS like every other stack component”; it is “incompatible with Mode 3 (air-gapped) — its cloud is an external dependency the invariants forbid”; and it “directly duplicates Langfuse, which already owns Layer 10 LLM engineering — breaks the ’non-overlapping responsibilities’ rule.” The ADR’s own summary of the deciding axis: “the deciding axis is Principle 11 + non-overlapping responsibilities, not capability.” LangSmith “MAY be used only as an optional developer-time convenience in cloud-connected Mode 1,” never as a required platform and never in Modes 2 or 3.
• Adopting LangGraph did not force adopting LangSmith. The ADR is explicit that the three libraries are “not a single decision.” Retaining Langfuse is what let the OS take LangGraph’s runtime capabilities without importing a proprietary dependency into the canon.
• It runs with no internet access. “Langfuse does not require internet access.” The only outbound call in a default OSS deployment is a version check against a cached GitHub API, which “will fail gracefully” when blocked. That is what makes air-gapped Mode 3 viable at this layer.
• Self-hosted is the same product as hosted. “It is the exact same codebase as Langfuse Cloud, just deployed on your own infrastructure,” and “there are no scalability limitations between the different versions.” Modes 2 and 3 do not get a degraded observability layer.
• OpenTelemetry ingestion keeps the layer substitutable. Because Langfuse is an OTel backend rather than a closed SDK, agents do not import a vendor tracing SDK. That is what makes the Layer 3 / Layer 4 split cheap to instrument and what would make a future replacement of the platform a configuration change rather than a rewrite.
• The data model matches the assigned responsibilities one-for-one. Nested typed observations give nested trace debugging; generation usage and cost details give token and cost attribution; prompt versions with labels give prompt versioning; scores over traces, observations, sessions and dataset runs give evaluations and quality scoring. No responsibility in Tech Stack §9 is a stretch of the product.

A note for readers coming from the Academy link

The Academy teaches LangSmith, deliberately, because that is what the LangChain certification tests and the exam is answered inside smith.langchain.com. That is a study decision, not an architecture decision — Synedrix OS ships on Langfuse, and a LangGraph agent with a LangSmith dependency fails the runtime compliance checklist. academy/appendix/A.5-langsmith-to-langfuse.md maps the two vocabularies term by term (run tree → trace with nested observations, thread → session, experiment → dataset run, feedback → score) and records the three places where the concept genuinely does not transfer.

Deployment and licensing link

Self-hosting. Documented deployment paths are Docker Compose on a VM or locally (“recommended for testing and low-scale deployments”), and for production scale Kubernetes via Helm, or Terraform on AWS, Azure and GCP. Releases are tagged semver on GitHub.

Licence — read this carefully. Langfuse is open core, not uniformly MIT. Per the repository’s root LICENSE:

• “All content that resides under the ee/, web/src/ee/, and/or worker/src/ee/ directories of this repository, if these directories exist, is licensed under the license defined in ee/LICENSE.”
• “Content outside of the above mentioned directories or restrictions above is available under the ‘MIT Expat’ license.”

ee/LICENSE states the position in its own words: “Langfuse is an open core project. Langfuse’s core is permissively licensed (MIT license). Certain parts of the periphery of Langfuse are commercially licensed and governed by this Enterprise License.” The Enterprise License permits copying and modifying “for development and testing purposes, without requiring a subscription,” but otherwise requires a valid Langfuse Enterprise License and forbids copying, merging, publishing, distributing, sublicensing or selling the software.

What this means in practice is narrow and good news for Synedrix OS. Langfuse’s self-hosting documentation states that “all core Langfuse features and APIs are available in Langfuse OSS (MIT licensed) without any limits.” The features that require LANGFUSE_EE_LICENSE_KEY are peripheral to Layer 10’s assigned responsibilities: project-level RBAC roles, protected prompt labels, data retention policies, audit logs, server-side ingestion masking, UI customisation, organization creators, the Org Management API and SCIM, and the Instance Management API. Tracing, prompt management, datasets, experiments, evaluators, scores and dashboards are all MIT.

Telemetry. “Langfuse self-hosted sends a small amount of deployment telemetry to Langfuse,” sent via PostHog Cloud. It does “not send raw traces, prompts, observations, scores, or dataset contents” — only instance-level aggregates: version, EE licence key if present, up to 30 email domains with user counts, project count, and counts of traces, scores, observations, datasets, dataset items and dataset runs for the reporting window. For Langfuse OSS this is on by default and can be disabled by setting TELEMETRY_ENABLED=false on all Langfuse application containers. For Langfuse Enterprise self-hosted, telemetry is used for licence compliance and cannot be disabled.

Open item. Tech Stack §9 records that “Langfuse is open source under MIT” and that the “self-hosted version stores all data locally with no external telemetry.” Both halves of that sentence need qualifying, and the same claim is repeated in the Deployment Model Spec platform table and in its Mode 3 checklist item “Langfuse is deployed locally (self-hosted) — no external telemetry.” The licence is open core, not flat MIT: ee/, web/src/ee/ and worker/src/ee/ are under a commercial Enterprise License, and the EE feature list includes data retention policies and audit logs, both of which a regulated Mode 3 customer is likely to ask for. The telemetry claim is true only after an explicit configuration step: OSS telemetry is on by default and requires TELEMETRY_ENABLED=false, and if an EE licence key is ever introduced, telemetry cannot be disabled at all — which would break the Mode 3 invariant of no external network dependency. Two decisions are needed: whether the canonical stack commits to OSS-only Langfuse, and whether TELEMETRY_ENABLED=false becomes a mandatory Mode 2/3 configuration item rather than an assumed default. Neither is resolved by this page, and the canonical documents are not amended by it.

Official documentation link

• Langfuse documentation home
• Observability overview
• Tracing data model — observations, traces, sessions
• Observation types
• Token & cost tracking
• Prompt management overview
• Evaluation core concepts
• OpenTelemetry (OTLP) ingestion
• LangGraph integration
• n8n integration — prompt-management node; no native tracing integration
• Self-host Langfuse — architecture and deployment options
• Networking (self-hosted) — “Langfuse does not require internet access”
• Telemetry (self-hosted) — what is sent and how to disable it
• Enterprise License Key (self-hosted) — the EE feature list
• Langfuse LICENSE — MIT Expat plus the ee/ carve-out
• Langfuse ee/LICENSE — Langfuse Enterprise License

Related Synedrix OS documents link

• Synedrix OS Tech Stack — normative platform responsibilities; §9 covers Langfuse, §13 records the LangSmith decision.
• ADR-OS-001 — Agent Runtime Split — §3.3 rejects LangSmith and retains Langfuse; the primary “why Langfuse” argument.
• Observability & Metrics Spec — what Langfuse owns against what the metrics layer owns; the trace_id correlation requirement.
• Agent Evaluation Spec — output-quality evaluation on Langfuse, including langfuse_dataset_ref.
• Outcome Spec — the Outcome Envelope and os.outcome.* events; the record Langfuse traces are not.
• LangGraph Runtime Implementation Guide — the compliance checklist requiring Langfuse export and no LangSmith dependency.
• Layer Taxonomy Table — Layer 10 definition and platform mapping.
• Core Principles — Principle 11 (Open by default, sovereign by design), the principle that decided this platform.
• Deployment Model Spec — Langfuse in all three modes; tracing local inference endpoints.

Synedrix OS · Platform reference · Langfuse