> ## Documentation Index
> Fetch the complete documentation index at: https://rasa.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Langfuse Integration

> Monitor, debug, and improve LLM applications with comprehensive tracing and analytics

[Langfuse](https://langfuse.com/) is an open-source observability platform designed specifically for LLM applications.
It provides comprehensive tracing, monitoring, and analytics capabilities that help you understand how your LLM-based components are performing in production.

## Installation

<Info>
  Before configuring Langfuse, you must install the `langfuse` package. Langfuse is included as an optional dependency in the `monitoring` extra group.
</Info>

To install Langfuse, use one of the following methods:

**Using pip:**

```bash theme={null}
pip install "rasa-pro[monitoring]"
```

**Using poetry:**

```bash theme={null}
poetry install --extras monitoring
```

Without installing the `langfuse` package, you will see an error message indicating that Langfuse is not available, and the integration will not be configured.

## Configuration

Langfuse is configured through the `endpoints.yml` file by adding a `langfuse` entry to the `tracing` section.
You can configure multiple tracing backends simultaneously (e.g., both Langfuse and [Jaeger](/docs/reference/integrations/tracing#configuring-a-tracing-backend-or-collector)).

Here is a basic configuration example:

```yaml title="endpoints.yml" theme={null}
tracing:
  - type: langfuse
    host: https://cloud.langfuse.com
    public_key: ${LANGFUSE_PUBLIC_KEY}
    private_key: ${LANGFUSE_PRIVATE_KEY}
```

### Configuration Options

| Option | Required | Description | Example |
| - | - | - | - |
| `type` | Yes | Must be set to `langfuse` | `langfuse` |
| `host` | Yes | The Langfuse server URL | `https://cloud.langfuse.com` |
| `public_key` | Yes | Your Langfuse public API key (must use `${VAR}` syntax for environment variables) | `${LANGFUSE_PUBLIC_KEY}` |
| `private_key` | Yes | Your Langfuse private API key (must use `${VAR}` syntax for environment variables) | `${LANGFUSE_PRIVATE_KEY}` |
| `timeout` | No | Request timeout in seconds | `30` |
| `debug` | No | Enable debug logging | `true` or `false` |
| `environment` | No | Environment label for traces | `production`, `staging`, `development` |
| `release` | No | Release version identifier | `v1.2.3` |
| `media_upload_thread_count` | No | Number of threads for media uploads | `4` |
| `sample_rate` | No | Sampling rate for traces (0.0 to 1.0) | `1.0` |

`public_key` and `private_key` **must** be set as environment variables, and in your `endpoints.yml` file, you reference them using the `${ENV_VAR_NAME}` syntax. For example:

1. **Set the environment variables** in your shell or deployment environment:

```bash theme={null}
export LANGFUSE_PUBLIC_KEY="<your-public-key>"
export LANGFUSE_PRIVATE_KEY="<your-private-key>"
```

2. **Reference these variables in your `endpoints.yml`:**

```yaml title="endpoints.yml" theme={null}
tracing:
  - type: langfuse
    host: https://cloud.langfuse.com
    public_key: ${LANGFUSE_PUBLIC_KEY}
    private_key: ${LANGFUSE_PRIVATE_KEY}
```

This ensures your secrets are not stored directly in configuration files but injected at runtime using environment variables.

### Multiple Tracing Backends

You can configure both Langfuse and other tracing backends (like [OTLP](/docs/reference/integrations/tracing#configuring-a-tracing-backend-or-collector)) simultaneously:

```yaml title="endpoints.yml" theme={null}
tracing:
  - type: otlp
    endpoint: my-otlp-host:4317
    insecure: false
    service_name: rasa
    root_certificates: ./tests/unit/tracing/fixtures/ca.pem
  - type: langfuse
    host: https://cloud.langfuse.com
    public_key: ${LANGFUSE_PUBLIC_KEY}
    private_key: ${LANGFUSE_PRIVATE_KEY}
```

## Traced Components

When Langfuse is configured, the following components automatically send traces:

### LLM-Based Components

* **Command Generators**: All LLM-based command generators that generate dialogue commands
* **Contextual Response Rephraser**: Components that rephrase responses using LLMs
* **Enterprise Search Policy**: Policy that uses LLMs to generate responses from search results
* **ReAct Sub Agent**: MCP-based sub agents that use LLMs for reasoning and tool execution
* **LLM-Based Router**: Components that route conversations using LLMs

### Embedding Operations

* **Flow Retrieval**: Semantic search operations when retrieving relevant flows
* **Enterprise Search Policy**: Vector search operations when finding relevant documents

## Trace Contents

Each trace sent to Langfuse includes the following information:

### Standard Trace Data

* **Timestamp**: When the LLM or embedding call was made
* **Input**: The prompt or query sent to the LLM/embedding model
* **Output**: The response or embedding vector returned
* **Latency**: Time taken for the request to complete
* **Token Usage**: Number of prompt tokens, completion tokens, and total tokens used
* **Cost**: Calculated cost based on token usage and model pricing

### Metadata

Each trace includes rich metadata to help you organize and filter traces:

* **Session ID**: The conversation session identifier
* **Tags**: Component name for easy filtering (e.g., `EnterpriseSearchPolicy`, `CompactLLMCommandGenerator`)
* **Custom Metadata**: A dictionary containing:
  * **Component Name**: The class name of the component making the call
  * **Agent ID**: The ID of the agent
  * **Model ID**: The ID of the trained model being used
  * **ReAct Sub Agent Name**: (For ReAct sub agents) The name of the sub-agent

#### Customizing Metadata

Custom components can override the `get_llm_tracing_metadata()` method to customize the metadata sent with each trace.


## Related topics

- [Tracing](/docs/pro/improve/tracing.md)
- [Rasa Pro Version Migration Guide](/docs/reference/changelogs/rasa-pro-migration-guide.md)
- [Rasa Pro Change Log](/docs/reference/changelogs/rasa-pro-changelog.md)
- [Set Up Your Agent on GCP](/docs/learn/deployment/gcp/gcp-playbook-setup-agent.md)
- [Set Up Your Agent on Azure](/docs/learn/deployment/azure/azure-playbook-setup-agent.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.