Skip to content

PAL-1104 document Langfuse server version detection and SDK v5 routing #1351

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
peter-vapi wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

PAL-1104 document Langfuse server version detection and SDK v5 routing #1351

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions fern/providers/observability/langfuse.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,23 @@ To make the most out of this integration, you can now use Langfuse's [evaluation
</Step>
</Steps>

## Server Version Detection and SDK Routing

When you save a Langfuse credential, Vapi probes your server's `/api/public/health` endpoint and automatically resolves the Langfuse server version. The credential stores this resolved version, and Vapi uses it to pick the export path for your traces:

- **Langfuse Cloud and self-hosted servers on version 3.63 or later** receive traces through the Langfuse JS SDK v5 OTLP export path.
- **Self-hosted servers on versions earlier than 3.63** continue to receive traces through the legacy v3 ingestion API.

You do not need to configure anything; routing follows the resolved server version. All Langfuse Cloud regions (`us.cloud.langfuse.com`, `hipaa.cloud.langfuse.com`, `jp.cloud.langfuse.com`, and `cloud.langfuse.com`) are fully supported, and self-hosted Langfuse v3 remains supported through the upstream v3 patch window ending January 31, 2027.

If Vapi cannot reach your server when you save the credential, you can enter the server version manually. The next successful probe corrects the stored version automatically.

## Troubleshooting

**Host URL is refused when saving.** Host URLs that redirect to a different origin are rejected because trace exports do not follow redirects. For example, `https://eu.cloud.langfuse.com` redirects to `https://cloud.langfuse.com`, so use `https://cloud.langfuse.com` directly. The error message names the URL to use.

**Traces stop appearing during calls.** If tracing fails during a call, for example because your server became unreachable or was upgraded or downgraded across the v3/v5 boundary, Vapi emits a call log error linking to the [credentials page](https://dashboard.vapi.ai/keys). Re-save your Langfuse credential there so Vapi can re-resolve the server version.

## Enrich Traces
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).

Expand Down
Loading