diff --git a/fern/apis/api/openapi.json b/fern/apis/api/openapi.json index 8616043ec..34aa9d3c9 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 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": [ 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. +