You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit e8e081b
Browse filesBrowse the repository at this point in the historyBrowse files
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
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.
10
10
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
+
11
13
<Frame>
12
14
<divclass="video-embed-wrapper">
13
15
<iframe
@@ -50,10 +52,16 @@ Under the **Observability Providers** section, you'll find an option for **Langf
50
52
-**Public Key**
51
53
-**Host URL** (US data region: `https://us.cloud.langfuse.com`, EU data region: `https://cloud.langfuse.com`)
52
54
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
+
53
61
Click **Save** to update your credentials.
54
62
55
63
<Framecaption="Langfuse in Vapi Integrations.">
56
-
<imgsrc="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
+
<imgsrc="../../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" />
57
65
</Frame>
58
66
59
67
</Step>
@@ -72,11 +80,68 @@ Example trace in Langfuse: https://cloud.langfuse.com/project/cloramnkj0002jz088
72
80
73
81
<Steptitle="Evaluate and Debug your Agent">
74
82
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.
76
86
77
87
</Step>
78
88
</Steps>
79
89
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.
**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
+
80
145
## Enrich Traces
81
146
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).
82
147
@@ -99,6 +164,10 @@ Examples:
99
164
- Store user segments ("user_type": "beta_tester")
100
165
- Log environment details ("env": "production")
101
166
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
+
102
171
**Tags**
103
172
104
173
Use the [`assistant.observabilityPlan.tags`](/api-reference/assistants/create#request.body.observabilityPlan.tags) field to add searchable labels.
0 commit comments