flow/docs/versioned_docs/version-1.9.0/Develop/integrations-langfuse.mdx

---
title: Langfuse
slug: /integrations-langfuse
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

[Langfuse](https://langfuse.com) is an open-source platform for LLM observability. It provides tracing and monitoring capabilities for AI applications, helping developers debug, analyze, and optimize their AI systems. Langfuse integrates with various tools and frameworks, including workflow builders and runtimes like Hanzo Flow.

This guide explains how to configure Hanzo Flow to collect [tracing](https://langfuse.com/docs/tracing) data about your flow executions and automatically send the data to Langfuse.

<iframe width="760" height="415" src="https://www.youtube.com/embed/SA9gGbzwNGU?si=eDKvdtvhb3fJCSbl" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

## Prerequisites

- An account in a [Langfuse Cloud](https://cloud.langfuse.com) or [Langfuse self-hosted](https://langfuse.com/self-hosting) instance
- A [running Hanzo Flow server](/get-started-installation) with a [flow](/concepts-flows) that you want to trace

:::tip
If you need a flow to test the Langfuse integration, see the [Hanzo Flow quickstart](/get-started-quickstart).
:::

## Set Langfuse credentials as environment variables {#langfuse-credentials}

1. Create a set of [Langfuse API keys](https://langfuse.com/faq/all/where-are-langfuse-api-keys).

2. Copy the following API key information:

    - Secret key
    - Public key
    - Base URL

    :::tip
    Hanzo Flow previously used `LANGFUSE_HOST` as the variable for the Langfuse base URL.
    This is still supported for backward compatibility, but `LANGFUSE_BASE_URL` is now the preferred environment variable and will be used if both values are set.
    :::

3. Set your Langfuse project credentials as environment variables.

    In the following examples, replace `SECRET_KEY`, `PUBLIC_KEY`, and `LANGFUSE_BASE_URL` with your API key details from Langfuse.
    Add the following entries to your `.env` file:

    ```bash
    LANGFUSE_SECRET_KEY=sk-...
    LANGFUSE_PUBLIC_KEY=pk-...
    LANGFUSE_BASE_URL=https://us.cloud.langfuse.com
    ```

4. Start Hanzo Flow with the configuration in the `.env` file:

    ```bash
    uv run flow run --env-file .env
    ```

5. Run a flow.

    Hanzo Flow automatically collects and sends tracing data about the flow execution to Langfuse.

6. View the collected data in your [Langfuse dashboard](https://langfuse.com/docs/analytics/overview).

    Langfuse also provides a [public live trace example dashboard](https://cloud.langfuse.com/project/cm0nywmaa005c3ol2msoisiho/traces/f016ae6d-4527-43f5-93ba-9d78388cd3d9).

## Disable Langfuse tracing

To disable the Langfuse integration, remove the [Langfuse environment variables](#langfuse-credentials), and then restart Hanzo Flow.

## Run Langfuse and Hanzo Flow with Docker Compose

As an alternative to the previous setup, particularly for self-hosted Langfuse, you can run both services with Docker Compose.

1. Create a set of [Langfuse API keys](https://langfuse.com/faq/all/where-are-langfuse-api-keys).

2. Copy the following API key information:

    - Secret key
    - Public key
    - Base URL

    :::tip
    Hanzo Flow previously used `LANGFUSE_HOST` as the variable for the Langfuse base URL.
    `LANGFUSE_HOST` is still supported for backward compatibility, but `LANGFUSE_BASE_URL` is the preferred environment variable.
    If both values are set, then `FLOW_BASE_URL` is used.
    :::

3. Add your Hanzo Flow credentials to your Hanzo Flow `docker-compose.yml` file in the `environment` section.

    The following example is based on the [example `docker-compose.yml`](https://github.com/hanzoai/flow/blob/main/docker_example/docker-compose.yml).

    ```yml
    services:
      flow:
        image: flowai/flow:latest # or another version tag on https://hub.docker.com/r/flowai/flow
        pull_policy: always               # set to 'always' when using 'latest' image
        ports:
          - "7860:7860"
        depends_on:
          - postgres
        environment:
          - FLOW_DATABASE_URL=postgresql://flow:flow@postgres:5432/flow
          # This variable defines where the logs, file storage, monitor data and secret keys are stored.
          - FLOW_CONFIG_DIR=app/flow
          - LANGFUSE_SECRET_KEY=sk-...
          - LANGFUSE_PUBLIC_KEY=pk-...
          - LANGFUSE_BASE_URL=https://us.cloud.langfuse.com
        volumes:
          - flow-data:/app/flow

      postgres:
        image: postgres:16
        environment:
          POSTGRES_USER: flow
          POSTGRES_PASSWORD: flow
          POSTGRES_DB: flow
        ports:
          - "5432:5432"
        volumes:
          - flow-postgres:/var/lib/postgresql/data

    volumes:
      flow-postgres:
      flow-data:
    ```

4. Start the Docker container:

    ```text
    docker-compose up
    ```

5. To confirm Langfuse is connected to your Hanzo Flow container, run the following command:

    ```sh
    docker compose exec flow python -c "import requests, os; addr = os.environ.get('LANGFUSE_BASE_URL'); print(addr); res = requests.get(addr, timeout=5); print(res.status_code)"
    ```

    If there is an error, make sure you have set the `LANGFUSE_BASE_URL` environment variable in your `docker-compose.yml` file.

    Output similar to the following indicates success:

    ```text
    https://us.cloud.langfuse.com
    200
    ```

## See also

* [Langfuse GitHub repository](https://github.com/langfuse/langfuse)