Skip to content

Commit e8e081b

Browse files
authored
PAL-1104 document Langfuse server version detection and SDK v5 routing (#1351)
* document langfuse server version detection and sdk v5 routing; add troubleshooting for redirecting host urls and tracing failures OpenCode session ID: ses_ece821fbeffeZ6yysKJ60XiP1X * Link Langfuse tracing docs from provider page The dashboard integration modal now links to this page instead of going straight to Langfuse's docs, so readers need a path to Langfuse's own tracing guide once they land here. - Add a reference to Langfuse's tracing documentation right after Vapi's framing paragraph, before the video walkthrough OpenCode session ID: ses_ece821fbeffeZ6yysKJ60XiP1X * Document Langfuse trace metadata limits - Note that each top-level metadata key maps to one trace attribute, with nested values serialized as JSON strings - Document the 512-key cap per trace and that excess keys beyond the first 512 are silently dropped - Clarify that Vapi's own identifiers (e.g. call ID) are added separately and always kept, even if user metadata reuses the same key name - Recommend keeping metadata small and filterable, storing large payloads elsewhere by reference Addresses reviewer feedback on vapi#23001 OpenCode session ID: ses_ece821fbeffeZ6yysKJ60XiP1X * Update Langfuse docs with version detection details and local screenshot Address Hal's four review comments on the Langfuse docs PR and move the credentials screenshot to self-hosted storage. - Describe the credential walkthrough in full: automatic version read on Host URL blur, the Check server version trigger, the save gate, the manual-entry fallback for proxied health endpoints, and the public-address requirement for the Host URL - Rewrite the routing section into four explicit cases, with Langfuse Cloud recognized by hostname regardless of when the credential was saved; note that a versionless self-hosted credential stays on the legacy path until re-saved, and remove the false claim that a later probe corrects the stored version automatically - Add a Trace IDs and Call Correlation section documenting the sha256-derived trace ID, metadata.callId as the recommended correlation key, and TypeScript/Python derivation snippets - Expand Troubleshooting to four entries covering every refusal the save path can return - Add the Langfuse Cloud legacy-API/evaluator cutoff of November 16, 2026, with a pointer to the LLM-as-a-judge migration guide - Host the credentials screenshot under fern/static/images/providers instead of hotlinking from langfuse.com, and update it to show the Server version row OpenCode session ID: ses_e4d07141affeH93cc94qFsDEgV * Update Langfuse docs for Cloud, HTTPS, and PCI behavior - Document that a Langfuse Cloud Host URL is recognized by hostname and saves immediately without a version check on blur; Check server version still works if a reading is wanted - Clarify that the Host URL must use https, not just resolve publicly: keys only travel over an encrypted connection, so an http:// Host URL is now refused at save with a message asking for https; existing http:// credentials keep exporting via the legacy v3 ingestion API but must be switched to https to save again - Scope the "traces stop appearing" error to the OTLP path and update its link from the credentials page to the Integrations page - Add a note that PCI-enabled assistants send nothing to Langfuse on either export path, including both conversation traces and tool calls OpenCode session ID: ses_e5728a7a4ffeE2BHw2MfzjCXxa
1 parent 19b194f commit e8e081b

2 files changed

Lines changed: 71 additions & 2 deletions

File tree

‎fern/providers/observability/langfuse.mdx‎

Lines changed: 71 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ slug: providers/observability/langfuse
88

99
Vapi natively integrates with Langfuse, allowing you to send traces directly to Langfuse for enhanced telemetry monitoring. This integration enables you to gain deeper insights into your voice AI applications and improve their performance and reliability.
1010

11+
This page covers connecting Langfuse to Vapi. For Langfuse's own guide to working with traces once they arrive, see the [Langfuse tracing documentation](https://langfuse.com/docs/tracing).
12+
1113
<Frame>
1214
<div class="video-embed-wrapper">
1315
<iframe
@@ -50,10 +52,16 @@ Under the **Observability Providers** section, you'll find an option for **Langf
5052
- **Public Key**
5153
- **Host URL** (US data region: `https://us.cloud.langfuse.com`, EU data region: `https://cloud.langfuse.com`)
5254

55+
For a self-hosted server, when you finish editing the Host URL, Vapi reads your Langfuse server's version from its unauthenticated `{Host URL}/api/public/health` endpoint, and the **Server version** row fills in with what it found. You can also trigger the check yourself with **Check server version**. **Save** stays disabled until a version is resolved, so every saved self-hosted credential knows which server it points at. Editing the Host URL clears the version, because a version belongs to the server it was read from.
56+
57+
A Langfuse Cloud Host URL needs no version: Cloud is recognized by its hostname, so **Save** is available right away and nothing is checked when you leave the field. **Check server version** still reads Cloud's version if you want to see it.
58+
59+
If your `/api/public/health` endpoint is hidden behind a proxy or firewall, a **Server version** field appears so you can state the version yourself (for example `3.63.0`). The Host URL itself must still use `https://` and resolve to a public address. Vapi only sends your keys over an encrypted connection, and it probes and exports from the public internet, so an `http://` Host URL, or one that resolves to a loopback, link-local, or private-network address, is refused regardless of the version you enter.
60+
5361
Click **Save** to update your credentials.
5462

5563
<Frame caption="Langfuse in Vapi Integrations.">
56-
<img src="https://langfuse.com/images/docs/vapi-integration-credentials.png" alt="Langfuse Credentials form under Observability Providers in the Dashboard with Secret Key, Public Key, and Host URL fields" />
64+
<img src="../../static/images/providers/langfuse-credentials.png" alt="Langfuse Credentials form under Observability Providers in the Dashboard with Secret Key, Public Key, and Host URL fields, a Server version row with a Check server version button, and a Save button" />
5765
</Frame>
5866

5967
</Step>
@@ -72,11 +80,68 @@ Example trace in Langfuse: https://cloud.langfuse.com/project/cloramnkj0002jz088
7280

7381
<Step title="Evaluate and Debug your Agent">
7482

75-
To make the most out of this integration, you can now use Langfuse's [evaluation](https://langfuse.com/docs/scores/overview) and [debugging](https://langfuse.com/docs/analytics/overview) tools to analyze and improve the performance of your voice AI agents.
83+
To make the most out of this integration, you can now use Langfuse's [evaluation](https://langfuse.com/docs/scores/overview) and [debugging](https://langfuse.com/docs/analytics/overview) tools to analyze and improve the performance of your voice AI agents.
84+
85+
If you are on Langfuse Cloud and already run LLM-as-a-judge evaluators, note that Langfuse retires its legacy evaluators on November 16, 2026; their [migration guide](https://langfuse.com/faq/all/llm-as-a-judge-migration) covers the upgrade, and their UI walks you through it.
7686

7787
</Step>
7888
</Steps>
7989

90+
## Server Version Detection and SDK Routing
91+
92+
Vapi exports traces over two paths: the modern OpenTelemetry (OTLP) path of the Langfuse JS SDK v5, and the legacy v3 ingestion API. Which one your credential uses follows the Langfuse server version resolved when you saved it:
93+
94+
- **Langfuse Cloud** always uses the OTLP path. Cloud is recognized by its hostname, so this applies to credentials saved at any time, including before this feature existed. All Cloud regions are supported: `us.cloud.langfuse.com`, `hipaa.cloud.langfuse.com`, `jp.cloud.langfuse.com`, and `cloud.langfuse.com`.
95+
- **Self-hosted on 3.63 or later** uses the OTLP path, once the credential has a detected server version.
96+
- **Self-hosted on versions earlier than 3.63**, and **any self-hosted credential with no detected version**, continues on the legacy v3 ingestion API.
97+
98+
<Note>
99+
If you self-host and saved your credential before version detection existed, it has no stored version, so your traces stay on the legacy path. That is a working path and nothing is interrupted, but upgrading your Langfuse server alone will not move you: **re-save the credential in the Vapi dashboard** so Vapi reads your server's current version. Nothing re-probes on its own, and the stored version changes only when you save again.
100+
</Note>
101+
102+
Self-hosted Langfuse v3 remains supported through the upstream v3 patch window ending January 31, 2027.
103+
104+
<Note>
105+
**Langfuse Cloud removes its legacy ingestion API and legacy features on November 16, 2026**, in every region. Vapi's own export is handled: Cloud credentials use the OTLP path, so your traces keep arriving. The one thing that may need your attention is in your Langfuse project rather than in Vapi: if you use Langfuse's legacy LLM-as-a-judge evaluators, migrate them before that date. See Langfuse's [LLM-as-a-judge migration guide](https://langfuse.com/faq/all/llm-as-a-judge-migration) and their [v4 upgrade guide](https://langfuse.com/faq/all/upgrade-to-langfuse-v4). Self-hosted servers are unaffected by this date and upgrade on your own schedule.
106+
</Note>
107+
108+
## Trace IDs and Call Correlation
109+
110+
On the OTLP export path, a trace ID is an OpenTelemetry trace ID: exactly 32 hexadecimal characters. A Vapi call ID is a UUID, so it cannot be used as a trace ID directly. Vapi therefore **derives** the trace ID from the call ID, as the first 32 hex characters of its SHA-256 hash. The derivation is deterministic, so the same call always produces the same trace ID.
111+
112+
Every trace also carries the call ID as `metadata.callId`, which is the recommended way to correlate. Filtering and searching by call ID in the Langfuse UI is unaffected.
113+
114+
<Warning>
115+
On the legacy v3 path, a trace's ID *was* the Vapi call ID verbatim. If your own code reads or writes Langfuse traces by using a call ID as the trace ID, for example scoring a trace from an end-of-call webhook, update it to either filter on `metadata.callId` or compute the derived ID.
116+
</Warning>
117+
118+
Computing the derived trace ID:
119+
120+
<CodeBlocks>
121+
```typescript title="TypeScript"
122+
import { createHash } from 'crypto';
123+
124+
const traceId = createHash('sha256').update(callId).digest('hex').slice(0, 32);
125+
```
126+
```python title="Python"
127+
import hashlib
128+
129+
trace_id = hashlib.sha256(call_id.encode()).hexdigest()[:32]
130+
```
131+
</CodeBlocks>
132+
133+
## Troubleshooting
134+
135+
**The Host URL redirects to another origin.** Host URLs that redirect elsewhere are refused, because trace exports do not follow redirects: the save would succeed and the exports would silently go nowhere. For example, `https://eu.cloud.langfuse.com` redirects to `https://cloud.langfuse.com`, so use `https://cloud.langfuse.com` directly, which is Langfuse's recommended base URL for EU-region projects and does not change where your data is stored. The error message names the URL to use instead.
136+
137+
**The Host URL must use HTTPS and resolve to a public address.** Vapi only sends your keys over an encrypted connection, so an `http://` Host URL is refused when you save, with a message asking for an `https://` one. Vapi also probes and exports from the public internet, so a Host URL that resolves to a loopback, link-local, or private-network address is refused. Entering a server version by hand bypasses neither rule. A credential saved earlier with an `http://` Host URL keeps sending traces over the legacy v3 ingestion API, but saving it again requires an `https://` Host URL.
138+
139+
**Vapi could not detect your server's version.** This means `{Host URL}/api/public/health` did not answer, or answered without a version, which is typical when a proxy or firewall sits in front of it. Enter your server's version yourself in the **Server version** field, as `major.minor.patch` exactly how your server's health endpoint reports it (for example `3.63.0`).
140+
141+
**Traces stop appearing during calls.** On the OTLP path, if a call's trace cannot be started or delivered, for example because your server became unreachable or was upgraded across the 3.63 boundary, Vapi writes an error into that call's logs with a link to the [Integrations page](https://dashboard.vapi.ai/settings/integrations). Re-save your Langfuse credential there so Vapi reads your server's current version; nothing re-detects it in the background.
142+
143+
**No traces from PCI calls.** When an assistant has [`compliancePlan.pciEnabled`](/security-and-privacy/pci) set, Vapi sends nothing from its calls to Langfuse: no conversation traces and no tool calls. This applies on both export paths.
144+
80145
## Enrich Traces
81146
Vapi allows you to enrich Langfuse traces by integrating [Metadata](https://langfuse.com/docs/tracing-features/metadata) and [Tags](https://langfuse.com/docs/tracing-features/tags).
82147

@@ -99,6 +164,10 @@ Examples:
99164
- Store user segments ("user_type": "beta_tester")
100165
- Log environment details ("env": "production")
101166

167+
<Note>
168+
On the Langfuse JS SDK v5 export path, each top-level metadata key becomes one trace attribute, and nested values are serialized as JSON strings. A trace keeps at most 512 metadata keys; any keys beyond the first 512 are dropped. Vapi's own identifiers, such as the call ID, are added separately and are always kept, even if your metadata uses the same key name. Keep metadata to a small set of filterable values and store large payloads elsewhere, referencing them by ID.
169+
</Note>
170+
102171
**Tags**
103172

104173
Use the [`assistant.observabilityPlan.tags`](/api-reference/assistants/create#request.body.observabilityPlan.tags) field to add searchable labels.
112 KB
Loading

0 commit comments

Comments
 (0)