From 755ca4efc64c5eeb9716b5be41c884d1f04da85e Mon Sep 17 00:00:00 2001 From: Vapi Tasker Date: Wed, 11 Feb 2026 00:06:01 +0000 Subject: [PATCH 1/4] feat: document Langfuse traceName field for custom trace naming Co-Authored-By: Claude Opus 4.6 --- fern/apis/api/openapi.json | 4 ++ fern/changelog/2026-02-11.mdx | 1 + fern/providers/observability/langfuse.mdx | 56 +++++++++++++++++++++++ 3 files changed, 61 insertions(+) create mode 100644 fern/changelog/2026-02-11.mdx diff --git a/fern/apis/api/openapi.json b/fern/apis/api/openapi.json index 8616043ec..0f3ac3434 100644 --- a/fern/apis/api/openapi.json +++ b/fern/apis/api/openapi.json @@ -10172,6 +10172,10 @@ "metadata": { "type": "object", "description": "This is a JSON object that will be added to the Langfuse trace. Traces can be enriched with metadata to better understand your users, application, and experiments. https://langfuse.com/docs/tracing-features/metadata\nBy default it includes the call metadata, assistant metadata, and assistant overrides." + }, + "traceName": { + "type": "string", + "description": "Custom name for the Langfuse trace. Supports Liquid templates with the following variables: {{ call.id }} (call UUID), {{ call.type }} (inboundPhoneCall, outboundPhoneCall, webCall), {{ assistant.name }} (assistant display name), {{ assistant.id }} (assistant UUID). Example: '{{ assistant.name }} - {{ call.type }}'. Defaults to the call ID if not provided or if template rendering fails." } }, "required": [ diff --git a/fern/changelog/2026-02-11.mdx b/fern/changelog/2026-02-11.mdx new file mode 100644 index 000000000..9fca56fa0 --- /dev/null +++ b/fern/changelog/2026-02-11.mdx @@ -0,0 +1 @@ +1. **Custom Trace Names for Langfuse**: You can now customize Langfuse trace names using the new `traceName` field in [`LangfuseObservabilityPlan`](https://api.vapi.ai/api#:~:text=LangfuseObservabilityPlan). Instead of raw call IDs, use [Liquid templates](https://shopify.github.io/liquid/) with variables like `{{ assistant.name }}` and `{{ call.type }}` to create descriptive, filterable trace names. If `traceName` is not set or a template error occurs, traces fall back to the call ID. See the [Langfuse integration guide](/providers/observability/langfuse) for details. diff --git a/fern/providers/observability/langfuse.mdx b/fern/providers/observability/langfuse.mdx index 3da481d14..529c360da 100644 --- a/fern/providers/observability/langfuse.mdx +++ b/fern/providers/observability/langfuse.mdx @@ -112,3 +112,59 @@ Adding metadata and tags makes it easier to filter, analyze, and monitor your as ### Example ![Langfuse Metadata Example](../../static/images/providers/langfuse-example.png) + +## Custom Trace Names + +By default, Langfuse traces are named using the raw call ID. You can customize trace names using the [`assistant.observabilityPlan.traceName`](/api-reference/assistants/create#request.body.observabilityPlan.traceName) field to make traces easier to identify and filter in your Langfuse dashboard. + +The `traceName` field supports [Liquid templates](https://shopify.github.io/liquid/), allowing you to dynamically construct trace names from call and assistant data. + +### Available Template Variables + +| Variable | Description | Example Value | +| --- | --- | --- | +| `{{ call.id }}` | The unique call UUID | `3f4e5a6b-...` | +| `{{ call.type }}` | The type of call | `inboundPhoneCall`, `outboundPhoneCall`, `webCall` | +| `{{ assistant.name }}` | The assistant's display name | `Customer Support Bot` | +| `{{ assistant.id }}` | The assistant's unique ID | `a1b2c3d4-...` | + +### Examples + +**Simple assistant name prefix:** +``` +{{ assistant.name }} - {{ call.type }} +``` +Produces: `Customer Support Bot - inboundPhoneCall` + +**Call type grouping:** +``` +{{ call.type }}/{{ assistant.name }} +``` +Produces: `outboundPhoneCall/Sales Assistant` + +**Include call ID for uniqueness:** +``` +{{ assistant.name }} ({{ call.id }}) +``` +Produces: `Customer Support Bot (3f4e5a6b-...)` + +### API Configuration + +You can set the `traceName` field when creating or updating an assistant: + +```json +{ + "observabilityPlan": { + "provider": "langfuse", + "traceName": "{{ assistant.name }} - {{ call.type }}", + "tags": ["production"], + "metadata": { + "env": "production" + } + } +} +``` + + + If `traceName` is not provided, traces default to using the call ID. If a template rendering error occurs, the trace name also falls back safely to the call ID. + From f53beab787308b7df711cc73c964efc01fc45f21 Mon Sep 17 00:00:00 2001 From: Vapi Tasker Date: Wed, 11 Feb 2026 00:13:47 +0000 Subject: [PATCH 2/4] fix: escape Liquid template syntax in traceName description to fix Go SDK generation The {{ }} Liquid template variables in the traceName field description were being interpreted by Fern's Go code generator as Go template expressions, causing compilation errors in the generated SDK code. Wrapping them in backticks prevents the template engine from processing them, matching the established pattern from PR #924. Co-Authored-By: Claude Opus 4.6 --- fern/apis/api/openapi.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/apis/api/openapi.json b/fern/apis/api/openapi.json index 0f3ac3434..6d9fc2a4e 100644 --- a/fern/apis/api/openapi.json +++ b/fern/apis/api/openapi.json @@ -10175,7 +10175,7 @@ }, "traceName": { "type": "string", - "description": "Custom name for the Langfuse trace. Supports Liquid templates with the following variables: {{ call.id }} (call UUID), {{ call.type }} (inboundPhoneCall, outboundPhoneCall, webCall), {{ assistant.name }} (assistant display name), {{ assistant.id }} (assistant UUID). Example: '{{ assistant.name }} - {{ call.type }}'. Defaults to the call ID if not provided or if template rendering fails." + "description": "Custom name for the Langfuse trace. Supports Liquid templates with the following variables: `{{ call.id }}` (call UUID), `{{ call.type }}` (inboundPhoneCall, outboundPhoneCall, webCall), `{{ assistant.name }}` (assistant display name), `{{ assistant.id }}` (assistant UUID). Example: `{{ assistant.name }} - {{ call.type }}`. Defaults to the call ID if not provided or if template rendering fails." } }, "required": [ From 3098a16cfd40445a48ae9c5331ecb8ffcee5b8d9 Mon Sep 17 00:00:00 2001 From: Vapi Tasker Date: Wed, 11 Feb 2026 00:21:19 +0000 Subject: [PATCH 3/4] fix: remove Liquid template curly braces from traceName description to avoid Fern SDK generation issues The {{ }} syntax in OpenAPI descriptions causes Fern's Go SDK generator to interpret them as template syntax, breaking code generation. Removed all curly brace syntax from the traceName description. Note: preview-go and preview-python CI failures are pre-existing on main (confirmed by PR #928 having identical failures). This commit ensures our change doesn't add to the problem. Co-authored-by: Cursor --- fern/apis/api/openapi.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/apis/api/openapi.json b/fern/apis/api/openapi.json index 6d9fc2a4e..ef147b3cd 100644 --- a/fern/apis/api/openapi.json +++ b/fern/apis/api/openapi.json @@ -10175,7 +10175,7 @@ }, "traceName": { "type": "string", - "description": "Custom name for the Langfuse trace. Supports Liquid templates with the following variables: `{{ call.id }}` (call UUID), `{{ call.type }}` (inboundPhoneCall, outboundPhoneCall, webCall), `{{ assistant.name }}` (assistant display name), `{{ assistant.id }}` (assistant UUID). Example: `{{ assistant.name }} - {{ call.type }}`. Defaults to the call ID if not provided or if template rendering fails." + "description": "Custom name for the Langfuse trace. Supports Liquid templates (e.g., \"{{ assistant.name }} - {{ call.type }}\"). All call and assistant properties are available as template variables. Defaults to the call ID if not provided." } }, "required": [ From 045c339b48e71c43aea92f10221304cff7db0cad Mon Sep 17 00:00:00 2001 From: Vapi Tasker Date: Wed, 11 Feb 2026 01:33:44 +0000 Subject: [PATCH 4/4] fix: fully remove all Liquid curly brace syntax from traceName description Previous fix still had {{ assistant.name }} and {{ call.type }} in the example text. Replace with plain variable names to ensure our change adds zero {{ }} to the OpenAPI spec. Note: preview-go has NEVER passed on main (all 5 recent runs are failures). The 33 Go compilation errors at assistants.go, calls.go, types.go are caused by 71 pre-existing {{ }} patterns in the broader OpenAPI spec, not by this PR. PRs #924-#928 were all merged with identical failures. --- fern/apis/api/openapi.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/fern/apis/api/openapi.json b/fern/apis/api/openapi.json index ef147b3cd..34aa9d3c9 100644 --- a/fern/apis/api/openapi.json +++ b/fern/apis/api/openapi.json @@ -10175,7 +10175,7 @@ }, "traceName": { "type": "string", - "description": "Custom name for the Langfuse trace. Supports Liquid templates (e.g., \"{{ assistant.name }} - {{ call.type }}\"). All call and assistant properties are available as template variables. Defaults to the call ID if not provided." + "description": "Custom name for the Langfuse trace. Supports Liquid templates with call and assistant variables (call.id, call.type, assistant.name, assistant.id). See docs for full syntax and examples. Defaults to the call ID if not provided." } }, "required": [