How the Langfuse OpenTelemetry integration works and when teams need it
Teams that already emit OpenTelemetry spans from their LLM applications can send those traces to self-hosted Langfuse without adopting a Langfuse-specific SDK. Langfuse accepts OpenTelemetry traces over OTLP at its /api/public/otel endpoint, so instrumented code and frameworks such as LangChain, LlamaIndex, CrewAI and AutoGen can export spans to it directly. This path suits organizations that already run an OpenTelemetry pipeline, want one instrumentation standard across services, or need to avoid vendor-specific client libraries in code that several teams own. The connection is easier to set up than it is to get right. Langfuse has to interpret incoming spans as LLM observations, traces and generations, so the mapping from your span names, span kinds and attributes to Langfuse's data model determines whether a trace is readable. Attribute naming matters as much as transport: a framework that records model, prompt and token usage under different keys than the ones Langfuse reads will send valid spans that display as incomplete. Credentials also need planning. Each Langfuse project has its own keys, so a collector or application that writes to several projects needs a clear mapping between services, collectors and projects before the first trace arrives. A working connection can still produce traces with missing user or session context. The application must set user and session identifiers on spans, typically through OpenTelemetry context or span attributes, and those values must reach every span in a trace, including spans created by background workers, tool calls or asynchronous steps. Without that propagation, traces appear and cost data may look correct while per-user and per-session views are empty. Confirm the exact attribute keys against the current Langfuse OpenTelemetry documentation and your framework versions, then test with a request from a known user and session and check the result in the Langfuse UI. Before committing to this approach, decide which team owns instrumentation conventions and who reviews changes to attribute naming. Teams that need prompt management, evaluations or scores tied to specific generations should compare how much of that workflow the OTLP path covers against the native SDKs, and plan to test the gaps rather than assume parity. The decision is easier when the application team, platform team and security reviewer agree on one trace schema, one set of project credentials per environment, and an acceptance test that checks user, session and cost fields on real traffic.
Components and settings involved in the trace path
A trace leaves the instrumented application, passes through an OpenTelemetry exporter and reaches the Langfuse Web container, then the Worker processes it into storage. Each hop has its own configuration and failure mode, so troubleshooting depends on knowing which component owns which step.
Instrumented application
This is the service or agent code that creates spans for model calls, tool calls and retrieval steps. Decide early which operations need spans and which user, session and environment attributes must be attached, because Langfuse can only group and filter what the application records. Check that sensitive inputs and outputs are captured only where your data policy allows.
OpenTelemetry SDK and exporter
The SDK batches spans and the OTLP exporter sends them to Langfuse. Confirm the exporter type, the endpoint URL and the project credential format against the current Langfuse OpenTelemetry documentation, since these details change between releases and are not covered here. Also confirm how the batch processor behaves when the endpoint is unreachable, because it determines whether spans are dropped or retried.
Framework instrumentation layer
Framework instrumentation such as the LangChain or LlamaIndex integrations creates spans automatically from framework calls. It can overlap with manual spans, which produces duplicate or nested traces. Review which instrumentation is enabled in each service and confirm it attaches to the same tracer provider as your SDK setup.
Langfuse Web container
The Web container exposes the OTLP endpoint at /api/public/otel and returns the HTTP response to the exporter. A successful response confirms the request was accepted, not that the trace is queryable. Confirm the public URL, TLS termination and any load balancer or ingress rules in front of Web, since misrouting here looks like missing traces from the exporter's side.
Langfuse Worker container
The Worker processes ingested events asynchronously and writes them to the analytical and metadata stores. Ingestion problems can appear after Web has already returned success, so a trace may be missing in the UI even though the exporter logged no error. Monitor Worker logs and CPU load together with Web, because Worker capacity is the usual scaling point for heavier trace volumes.
Storage behind Web and Worker
PostgreSQL holds application metadata, ClickHouse stores trace and observation data, Redis or Valkey supports queueing and caching, and S3-compatible blob storage holds larger payloads. Each store needs its own sizing, backup and network rules, and a fault in any one can stop tracing even when both containers are healthy. Confirm the versions and minimum resources in the Langfuse scaling guide before sizing.
Native SDK, framework instrumentation or generic OTEL: which path to choose
This table compares the three ways to send traces to self-hosted Langfuse and the operational cost of each. Read each row for the team profile it suits and what you must maintain after go-live. The main takeaway is that Python SDK v5 and JS/TS SDK v6 require Langfuse v4.59.0 or later, so your SDK choice also sets your server upgrade path.
| Path | When it fits | Operational cost | Version and mapping risk |
|---|---|---|---|
| Langfuse native SDK | New Python or JS/TS service with no existing tracing platform. Team wants Langfuse-specific features with less mapping work. | Pin SDK versions to the server. Python SDK v5 and JS/TS SDK v6 need Langfuse v4.59.0 or later, so SDK upgrades follow server upgrades. | Lowest mapping risk because attributes are set through the SDK. Still test user and session propagation. |
| Framework OpenTelemetry instrumentation to Langfuse OTLP | Application built on LangChain, LlamaIndex, CrewAI or AutoGen that already uses the framework's OTEL support and sends traces to Langfuse's /api/public/otel endpoint directly. | No collector to run. Instrumentation library versions move with the framework, so review them on each framework upgrade. | Attribute names come from the framework and Langfuse's mapping. Confirm user and session attributes appear in traces for each framework version. |
| Generic OpenTelemetry pipeline with collector | Mixed vendors or an existing OTEL platform where traces also go to other backends. Platform team wants one routing layer. | A collector to deploy, configure, patch and monitor. Exporter and processor settings must stay in step with Langfuse's OTLP requirements. | Attribute mapping happens in collector processors and must be tested end to end. Highest risk of silent loss of user or session fields. |
Building the OTLP integration from first trace to shared project
This sequence takes a team from one verified trace in a non-production Langfuse instance to a shared setup used by several services. Each step closes with a check that confirms the previous step worked before the next one starts. The result is a documented integration that engineers can reproduce in other environments.
Create the project and API keys
The platform team creates a dedicated Langfuse project for the integration in a non-production instance, then generates a public and secret key pair for it. Store both keys in your secrets manager and inject them into the test application at runtime, never in source code or configuration committed to a repository. Using a separate project for the first test keeps its traces apart from other activity. The check is that the project is visible to the test user and the application can read the key pair from its runtime secret.
Point the OTLP exporter at Langfuse
The engineer responsible for the test application configures the OpenTelemetry SDK exporter to send OTLP traces to the /api/public/otel endpoint on the non-production instance, using the project credentials. Confirm the transport settings, authentication header format and any project identifier against the current Langfuse OpenTelemetry documentation for your SDK version, since these details change between releases. Leave other exporters disabled during the test so every span has one destination. The check is that the application starts with no exporter errors in its logs and the instance hostname resolves from the application host.
Instrument one framework and send a single request
The application engineer enables OpenTelemetry instrumentation for one framework, such as LangChain or LlamaIndex, and sends one known request with a fixed input. Before sending, write down the expected shape of the trace: the root span, the number of model calls, tool calls or retrieval steps, and the parent-child nesting. Record the request identifier and the time the request was sent so the trace can be matched later. The check is a written expectation document stored with the test notes, so the comparison in the next step is against a fixed reference rather than memory.
Confirm the trace and span hierarchy
The engineer opens the Langfuse UI, finds the trace for the known request and compares its trace ID with the one the application logged. Count the spans and check that their nesting matches the expected shape from the previous step, with a single root span and the model and tool calls under the correct parents. Verify that model inputs, outputs and token usage appear where the framework is expected to place them. The check passes when the trace ID matches and the span count equals the expected count. If it does not, fix the instrumentation before moving on.
Decide whether a collector is needed
The platform architect decides whether an OpenTelemetry Collector sits between the applications and Langfuse. Add one only if the design requires fan-out to Langfuse and another backend, central filtering or redaction before data leaves the network, or sampling at a gateway. If direct export from each service meets the requirements, skip the collector and record that decision with its reasons. If a collector is added, send the same known request through it and confirm the trace ID and span count arrive unchanged. The check is either a recorded decision or a repeated test that matches the step 4 results.
Roll out to other services
Each owning team repeats the configuration for its services, either in a dedicated project or in a shared project with agreed tagging rules. Standardize the names used for user and session attributes so that traces from different services can be filtered together, and document those conventions in the team runbook. Confirm the exact attribute keys against the Langfuse documentation for your SDK version. Run one known request per service and check that the trace lands in the agreed project with the user and session attributes populated. The check is a short sign-off table listing each service, its project and a passing test trace.
Propagating user and session attributes so traces are searchable
Traces only become useful for debugging a complaint or auditing a session if the user and session identifiers are on the spans that Langfuse stores. Those identifiers do not appear by default when an OpenTelemetry SDK exports a trace, so they have to be set in code, and the place to set them is usually a middleware or context wrapper that runs for every inbound request. Before any code is written, confirm the exact attribute names that the Langfuse OpenTelemetry mapping expects for user and session identifiers, using the current Langfuse OpenTelemetry documentation and the SDK version your team pins. Names that look reasonable but do not match the mapping will send data that the Langfuse UI does not index as a user or session, and the failure is silent.
Common failure modes cluster around where and when the attributes are set. The first is attaching them to the wrong span: a request often produces a root span from the web framework and several child spans from the LLM framework, and the attribute must sit on the span the team will filter on, or be propagated to children deliberately. The second is setting identifiers after the LLM call has started. A span that has already emitted its model call, or a context that was captured before authentication completed, will carry no user at all. Test this by sending a request as a known test user and confirming that the resulting trace shows that user before any other review starts.
Background jobs, queues and scheduled tasks are the third failure mode. Their work runs outside the request context, so a worker that processes an LLM step without reattaching the session identifier will produce traces that cannot be grouped with the user session that triggered them. The fourth is more serious: in multi-tenant services that reuse objects, thread-local storage or long-lived async context, one request can inherit another user's identifier. Ask the engineering team how context is scoped in their runtime, and include a test in which two concurrent requests for different users are checked for correct attribution.
Choose identifiers that are stable and do not reveal a person. An internal account key, a pseudonymous customer reference or a salted hash is usually better than an email address or a national identifier, because these values appear in the trace UI, are visible to anyone with project access and may be retained under the retention policy you configure. Confirm with your privacy and legal owners which fields are personal data in your jurisdiction, and whether retention of traces needs to match your records policy. Also decide who can view traces at all, since the identifier is only as sensitive as the people who can read it.
Document the decision as a short attribute standard before implementation: the attribute names, the source of each value, the span they belong to, the propagation rule for child and background spans, and the review owner. Then include a verification step in the build plan, with one trace per test case checked in the Langfuse UI for user, session, span placement and absence of unwanted personal data. This standard also gives the security and compliance reviewers something concrete to approve, which is faster than reviewing traces after the fact.
What drives the integration effort and how to keep each part down
This table lists the factors that change how much work an OpenTelemetry tracing integration with Langfuse takes, and how to reduce each one. Read each row as a lever you can set before work starts, with the reduction column showing the design choice that keeps it contained. The main takeaway is that most effort comes from decisions made early, so agree them in the written scope before estimating.
| Driver | Why it changes effort | How to keep it down |
|---|---|---|
| Services and frameworks to instrument | Each service, worker or agent runtime needs its own OTLP exporter setup, resource naming and framework hooks such as LangChain or LlamaIndex callbacks. | Instrument one reference service first, then reuse its configuration and checklist for the remaining services. |
| Languages and SDK versions | Each language runtime and OpenTelemetry SDK version behaves differently for span context, async work and exporter configuration, so testing multiplies. | Limit the first phase to the languages in production use and pin SDK versions in a shared dependency list. |
| Trace volume and server sizing | Higher span volume raises ingestion load on Langfuse Worker, ClickHouse and PostgreSQL, which changes sizing and the load tests needed before go-live. | Agree expected trace volume per environment early and confirm sizing against the Langfuse scaling guide before instrumenting every path. |
| Collector introduced or not | A direct OTLP export is simpler to operate, while a collector adds a component to deploy, configure, monitor and secure across environments. | Decide up front whether a collector is needed for batching, redaction or routing, and document that single decision for all teams. |
| Separate environments and projects | Test, staging and production usually need separate Langfuse projects and keys, so each environment needs its own configuration and verification. | Standardize one environment variable set and key naming pattern, then promote the same configuration through each environment. |
| Depth of attribute propagation | User, session and custom metadata must follow requests across async calls, queues and service boundaries, which is where most missing or mislabeled traces appear. | Define a fixed attribute contract with required names, types and where each value is set, and enforce it in shared middleware. |
| Shared instrumentation middleware | Without shared code, every team writes its own span attributes and exporter setup, which increases review, drift and support work. | Build one internal library or middleware package for setup, attributes and sampling, and version it with the services that use it. |
| Sampling decisions | Sampling changes how many traces are sent and which requests can be investigated, so unclear rules cause rework in both code and sizing. | Agree sampling rates and rules for each environment and workload type before implementation, and record them in the attribute contract. |
| Compliance review of prompts and outputs | Captured prompts and model outputs may contain personal or regulated data, so reviewers must approve what is captured, masked or excluded before production use. | Classify prompt and output fields early, decide what to redact at the source, and confirm retention and masking options against your edition and key requirements. |
Protecting credentials and sensitive content in traces
Traces sent from an application to Langfuse can carry API keys, user data and proprietary prompt content, so the protections start before the first span is exported. The cards below cover where credentials live, how traffic reaches the endpoint, who can read traces and what gets captured in the first place.
Store project keys as secrets
The public and secret keys for a Langfuse project authenticate every OTLP export, so they belong in a secrets manager or the platform's secret store, injected into the runtime at start. Keep them out of source control, container images, build logs and sample notebooks. Check that your OpenTelemetry exporter configuration reads these values from the environment, and that rotation can be done without a code change.
Separate keys per environment
Create distinct Langfuse projects or key pairs for development, staging and production, so a leaked development key cannot write into production traces and test traffic does not mix with live user data. Record which application, service account and environment owns each key. Confirm during rollout that every deployment resolves to the key for its own environment, since a copied configuration file is a common cause of cross-environment traces.
Encrypt the path to the endpoint
Export traces only to the Langfuse endpoint over TLS, using the HTTPS address of your self-hosted instance. Confirm that certificates are valid and trusted by the application runtime, including any private certificate authority used inside your network, and that the exporter does not fall back to an unencrypted address. Where egress is restricted, allow only the Langfuse hostname from the workloads that send traces.
Limit who can view traces
Trace data often exposes prompts, outputs and user identifiers to anyone with access to the UI or the public API. Decide which people need read access, which need write access to configuration, and which should have no access at all. Project-level roles that narrow access by project need an Enterprise license key. Review membership on a set schedule and remove accounts when people change roles.
Decide what is captured before rollout
Prompts, completions and tool inputs can contain personal data, health or financial details, or confidential business information. Before enabling auto-instrumentation, list the fields each framework records by default, then decide which content to capture in full, which to summarize and which to drop in the application. Record the decision with the data owners, since changing it later means reprocessing or deleting data already stored.
Plan masking and retention
Server-side data masking and data retention policies are Enterprise features that need a license key, according to the Langfuse license key documentation. Without them, masking happens in the application before export and retention is handled by your own cleanup process. Also confirm the exact masking options available in the release you deploy, and check how the UI SSO enforcement is configured separately from the trace endpoint, since restricting who signs in does not change what the endpoint accepts.
Testing that traces arrive, attribute correctly and fail safely
Before handover, the team should prove that traces from every instrumented application reach self-hosted Langfuse, carry the right identity and session context, and do not hurt the application when Langfuse misbehaves. Treat this as an acceptance test with written pass criteria, not a quick look at the dashboard. The plan has four parts: functional attribution checks, a load test at expected volume, a failure test, and operational checks for restarts and credential changes. Start with a repeatable test request for each framework in use, such as LangChain, LlamaIndex or a plain OpenTelemetry SDK service. Each request should send a known user identifier and session identifier, and a fixed prompt that makes the result easy to find. Then check three things in the Langfuse UI and API. Each span should appear with the parent-child structure your code is supposed to produce, for example a chain span with model and tool spans beneath it. The user and session filters should return the test traffic and nothing unrelated. Finally, the values on the trace should match the values you sent, character for character, because attribute names often differ between native SDKs and generic OTEL exporters. Next, run a load test at the trace volume you expect in production, measured in traces per second and total spans per hour from your own capacity model. Confirm that every trace arrives, that ingestion latency stays within what your operations team has agreed, and that Worker and ClickHouse resource use stays within headroom. Record the worker scaling behavior, since Langfuse recommends scaling worker containers on CPU load. The volume figures must come from your own estimate, not from this page. The failure test is the one most often skipped. Stop or block network access to the Langfuse endpoint while the application keeps receiving traffic. Confirm that application requests still succeed, that response times do not climb because the exporter is blocking, and that the application logs show tracing errors without turning them into request failures. Then restore connectivity and confirm whether the buffered spans are delivered or dropped, and document that behavior so the operations team knows what a Langfuse outage costs in lost observability. Finally, verify the operational edges. Restart the Langfuse Worker and confirm that traces sent before and after the restart both appear. Rotate the public and secret API keys used by the applications, then send a new test request and confirm it appears under the new credentials, while checking that the old credentials are rejected and that no traffic is silently discarded during the change. Save the test scripts, the request inputs, screenshots or API exports of results, and the pass or fail record for each check. Have the client sign off on this evidence as the acceptance record for handover.
Questions buyers ask before bringing in help with the Langfuse OpenTelemetry integration
How much effort does a Langfuse OpenTelemetry integration take?
Effort depends mainly on how many services emit traces, which languages they use and how much attribute work is required. A single service that already uses an OpenTelemetry SDK and a supported framework is a small change: configure the exporter, point it at the Langfuse OTLP endpoint at /api/public/otel and verify that spans appear. Effort rises with each additional service or language, with the number of user and session attributes that must propagate consistently, and with any requirement to redact fields before they leave the application. The cost has two parts: engineering time to instrument and test, and review time from the owners who approve what is captured. Ask any provider for a written scope that lists services, languages, frameworks, attributes and environments. Compare quotes against that same list so each provider prices identical work.
How long does an OpenTelemetry integration with Langfuse take?
No duration can be stated responsibly without a defined scope, because the timeline follows service count, language mix and attribute requirements. A pilot on one service with a clear instrumentation pattern is the shortest path to working traces. Adding services in several languages adds test and review cycles, and agreeing an attribute contract across teams often takes longer than the code change itself. Environment access, production change approvals and the availability of each service owner also set the pace. Ask for a timeline tied to milestones in the written scope, along with a list of what the client must provide at each step. If the Langfuse server is not yet running, its deployment is a separate phase and should be scheduled on its own.
What does the client need to provide for the integration?
The client provides access, decisions and sign-off. Engineers need access to the source repositories or deployment configuration of each instrumented service, plus the non-production and production environments where traces will be tested. A named owner should maintain the attribute contract, meaning the agreed names and meanings of user, session and custom attributes, and resolve disagreements between teams. Security or privacy reviewers should approve which fields may be captured, because trace content can include prompts, outputs and user identifiers. Someone must also confirm the Langfuse endpoint and credentials each environment will use. Without these inputs, work stalls at the first review gate, so confirm owners before the scope is signed.
Can an internal team set up Langfuse OpenTelemetry tracing alone?
Yes, for a single service that follows a clear, documented pattern. One team that already runs OpenTelemetry can add the exporter, configure the Langfuse OTLP endpoint and confirm that spans and attributes appear as expected. The difficulty grows with several services in different languages, because each runtime needs its own SDK setup and its own propagation of user and session attributes. Consistency across those services is the harder problem, and it usually requires a shared attribute contract and shared test cases. An internal team should also plan how trace content will be reviewed before production. If the team lacks OpenTelemetry experience or cannot dedicate time to owning the contract, an outside partner can take on design and build work under a written scope.
Does Langfuse OpenTelemetry tracing need an SDK version plan?
Yes. SDK versions and the Langfuse server version should be planned together. Langfuse documents that Python SDK v5 and JavaScript and TypeScript SDK v6 need Langfuse v4.59.0 or later, so an SDK upgrade cannot proceed on a server that runs an earlier release. Applications using native Langfuse SDKs and applications using generic OpenTelemetry exporters may follow different upgrade paths, so list both in your inventory. Pin SDK and framework versions in each service, record the server release each environment runs and test trace output after every upgrade. Framework instrumentation packages for LangChain or LlamaIndex change on their own schedules, so include them. Confirm the current compatibility details in the Langfuse documentation before setting any dates.
What happens after go-live for Langfuse tracing?
After go-live, the integration needs an owner for attribute changes, SDK updates and trace quality monitoring. New services and new framework versions need the same review as the first ones. Watch for missing traces, dropped attributes and unexpected content in captured fields, and keep a runbook for rotating credentials. Server upgrades follow Langfuse's upgrade guides: updates within a major version apply database migrations at startup, while major versions such as v3 to v4 need dedicated planning, and that guide requires ClickHouse 25.12 or later. DeployOpen offers ongoing support, upgrades and continuous testing as retainers, and the scope of that work is set in writing. Ask whether support covers instrumentation changes, server upgrades or both.
How does the scope and quote process work for this integration?
Most engagements are fixed-scope, so the written scope is agreed before any work starts. DeployOpen does not publish a price list, and a quote follows from that scope. The scope should list services, languages, frameworks, attribute requirements, environments, review gates and deliverables. Ask for the split between one-time build work and any recurring support, and for the assumptions behind each line. Also ask which client inputs, such as access, owners and approvals, would change the price or timeline if they arrive late. Confirm how changes are handled after signing, including new services added mid-project. A quote built from a shared list of services and attributes is far easier to compare across providers.
How DeployOpen scopes, builds and hands over the Langfuse OTLP integration
DeployOpen plans, implements and documents the OpenTelemetry tracing path into a self-hosted Langfuse instance inside your own infrastructure. Each engagement starts from a written scope that names the applications, frameworks and attributes to be traced, and the work is delivered and handed over against that scope.
How we scope
- Inventory the applications and LLM frameworks that will send traces to the /api/public/otel endpoint.
- Agree in writing which propagated user and session attributes are required for each application.
- Confirm the target Langfuse version, since SDK and server compatibility depends on it.
How we build
- Instrument each service with OpenTelemetry SDKs and framework hooks, with the OTLP exporter pointed at your instance.
- Test trace structure, attribute propagation and export behavior in a non-production Langfuse environment first.
- Record the chosen approach for each application, whether a native Langfuse SDK or generic OTEL export, and why.
How we hand over
- Deliver instrumentation code, configuration files and a runbook covering credentials, endpoints and attribute conventions.
- Walk your engineers through verifying traces in the Langfuse UI and troubleshooting missing or partial spans.
- Document known gaps, such as frameworks that emit spans your team must review, so ownership is clear at handover.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after go-live.
- Retainers can cover updates to instrumentation when Langfuse or your SDK versions change.
- Confirm with us in the written scope which support responsibilities stay with your internal team.
