English | 中文

This is a fork of Langfuse, which we have deeply customized and optimized for application scenarios, including:

• 🚀 Performance Optimization: ClickHouse AMT table optimization, connection pool optimization, etc.
• 🏢 Enterprise Deployment: Harbor image registry support, one-click deployment scripts
• ⚙️ Flexible Configuration: Rich environment variable configuration, initialization configuration
• 📊 Enhanced Features: Internationalization, open-source external evaluation system Bridge, dataset run optimization

# Clone repository
git clone <your-repo-url>
cd langfuse

# Copy environment variable template
cp env.template .env

# Edit environment variables as needed
vim .env

# Build images
./deploy.sh build

# Full deployment (including middleware)
./deploy.sh start full

After all services are started successfully, you can access the web page through WEB_HTTP_PORT or WEB_HTTPS_PORT, such as http://localhost:3001.

The Bridge service is used to configure remote Ragflow On OceanBase application invocation and scoring (via SDK/API).

When editing a Remote Dataset Run Trigger in Langfuse, you need to configure the following information:

• Webhook URL: http://<Bridge-service-host>:9002/webhook/dataset/process-items

  • Replace <Bridge-service-host> with the actual Bridge service host address

• Default Configuration: Refer to the BRIDGE-PAYLOAD.md document for complete payload configuration instructions

# Build all images
./deploy.sh build

# Or use Docker Compose
docker compose -f docker-compose.build.yml build

Langfuse is an open source LLM engineering platform. It helps teams collaboratively develop, monitor, evaluate, and debug AI applications. Langfuse can be self-hosted in minutes and is battle-tested.

• LLM Application Observability: Instrument your app and start ingesting traces to Langfuse, thereby tracking LLM calls and other relevant logic in your app such as retrieval, embedding, or agent actions. Inspect and debug complex logs and user sessions. Try the interactive demo to see this in action.

• Prompt Management helps you centrally manage, version control, and collaboratively iterate on your prompts. Thanks to strong caching on server and client side, you can iterate on prompts without adding latency to your application.

• Evaluations are key to the LLM application development workflow, and Langfuse adapts to your needs. It supports LLM-as-a-judge, user feedback collection, manual labeling, and custom evaluation pipelines via APIs/SDKs.

• Datasets enable test sets and benchmarks for evaluating your LLM application. They support continuous improvement, pre-deployment testing, structured experiments, flexible evaluation, and seamless integration with frameworks like LangChain and LlamaIndex.

• LLM Playground is a tool for testing and iterating on your prompts and model configurations, shortening the feedback loop and accelerating development. When you see a bad result in tracing, you can directly jump to the playground to iterate on it.

• Comprehensive API: Langfuse is frequently used to power bespoke LLMOps workflows while using the building blocks provided by Langfuse via the API. OpenAPI spec, Postman collection, and typed SDKs for Python, JS/TS are available.

Managed deployment by the Langfuse team, generous free-tier, no credit card required.

Run Langfuse on your own infrastructure:

• Local (docker compose): Run Langfuse on your own machine in 5 minutes using Docker Compose.

  # Get a copy of the latest Langfuse repository
  git clone https://github.com/langfuse/langfuse.git
  cd langfuse
  
  # Run the langfuse docker compose
  docker compose up

• VM: Run Langfuse on a single Virtual Machine using Docker Compose.

• Kubernetes (Helm): Run Langfuse on a Kubernetes cluster using Helm. This is the preferred production deployment.

• Terraform Templates: AWS, Azure, GCP

See self-hosting documentation to learn more about architecture and configuration options.

Instrument your app and start ingesting traces to Langfuse, thereby tracking LLM calls and other relevant logic in your app such as retrieval, embedding, or agent actions. Inspect and debug complex logs and user sessions.

1. Create Langfuse account or self-host
2. Create a new project
3. Create new API credentials in the project settings

The @observe() decorator makes it easy to trace any Python LLM application. In this quickstart we also use the Langfuse OpenAI integration to automatically capture all model parameters.

pip install langfuse openai

LANGFUSE_SECRET_KEY="sk-lf-..."
LANGFUSE_PUBLIC_KEY="pk-lf-..."
LANGFUSE_HOST="https://cloud.langfuse.com" # 🇪🇺 EU region
# LANGFUSE_HOST="https://us.cloud.langfuse.com" # 🇺🇸 US region

from langfuse import observe
from langfuse.openai import openai # OpenAI integration

@observe()
def story():
    return openai.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "What is Langfuse?"}],
    ).choices[0].message.content

@observe()
def main():
    return story()

main()

See your language model calls and other application logic in Langfuse.

Public example trace in Langfuse

1. Data Migration Issues

   • If data migration is not completed normally or tables are missing, you can manually execute the migration. It is recommended to manually execute it to ensure data migration completes successfully:

   sudo docker exec langfuse-langfuse-web-1 sh -c "cd /app/packages/shared && CLICKHOUSE_CLUSTER_ENABLED=false node clickhouse/scripts/migrate.js up unclustered"

2. Unstable Traces List Display

   • AMT capability is enabled, but some base table data has not been synchronized to AMT data tables.
   • Execute the synchronization script. First, check ClickHouse connection information, then execute synchronization:

   # Query trace count in base table
   docker exec langfuse-clickhouse-1 clickhouse-client --query "SELECT count(*) as traces_count FROM traces FINAL WHERE project_id = 'cmheghiek000aqlqznqlq17c7' AND is_deleted = 0" 2>/dev/null || echo "Need to check ClickHouse connection"
   
   # Query trace count in AMT table
   docker exec langfuse-clickhouse-1 clickhouse-client --query "SELECT count(*) as amt_count FROM traces_all_amt WHERE project_id = 'cmheghiek000aqlqznqlq17c7'" 2>/dev/null || echo "Need to check ClickHouse connection"

   • If the base table and AMT table record counts are inconsistent, execute the synchronization script:

   docker exec -i langfuse-clickhouse-1 clickhouse-client << 'EOF'
   -- Synchronize data for specified project to traces_null table
   INSERT INTO traces_null
   SELECT
      project_id,
      id,
      timestamp as start_time,
      null as end_time,
      name,
      metadata,
      user_id,
      session_id,
      environment,
      tags,
      version,
      release,
      bookmarked,
      public,
      [] as observation_ids,
      [] as score_ids,
      map() as cost_details,
      map() as usage_details,
      coalesce(input, '') as input,
      coalesce(output, '') as output,
      created_at,
      updated_at,
      event_ts
   FROM traces FINAL
   WHERE is_deleted = 0
   AND project_id = 'cmheghiek000aqlqznqlq17c7'
   ;
   EOF

   • Verify synchronization results:

   docker exec langfuse-clickhouse-1 clickhouse-client --query "SELECT count(*) as amt_count FROM traces_all_amt WHERE project_id = 'cmheghiek000aqlqznqlq17c7'"
   
   docker exec langfuse-clickhouse-1 clickhouse-client --query "SELECT count(*) as amt_7d_count FROM traces_7d_amt WHERE project_id = 'cmheghiek000aqlqznqlq17c7'"
   
   docker exec langfuse-clickhouse-1 clickhouse-client --query "SELECT count(*) as amt_30d_count FROM traces_30d_amt WHERE project_id = 'cmheghiek000aqlqznqlq17c7'"

   If the data counts in all three tables are consistent, the data synchronization is correct.

Finding an answer to your question:

• Our documentation is the best place to start looking for answers. It is comprehensive, and we invest significant time into maintaining it. You can also suggest edits to the docs via GitHub.
• Langfuse FAQs where the most common questions are answered.
• Use "Ask AI" to get instant answers to your questions.

Support Channels:

• Ask any question in our public Q&A on GitHub Discussions. Please include as much detail as possible (e.g. code snippets, screenshots, background information) to help us understand your question.
• Request a feature on GitHub Discussions.
• Report a Bug on GitHub Issues.
• For time-sensitive queries, ping us via the in-app chat widget.

Your contributions are welcome!

• Vote on Ideas in GitHub Discussions.
• Raise and comment on Issues.
• Open a PR - see CONTRIBUTING.md for details on how to setup a development environment.

This repository is MIT licensed, except for the ee folders. See LICENSE and docs for more details.

Top open-source Python projects that use Langfuse, ranked by stars (Source):

Repository	Stars
langgenius / dify	54865
open-webui / open-webui	51531
lobehub / lobe-chat	49003
langflow-ai / langflow	39093
run-llama / llama_index	37368
chatchat-space / Langchain-Chatchat	32486
FlowiseAI / Flowise	32448
mindsdb / mindsdb	26931
twentyhq / twenty	24195
PostHog / posthog	22618
BerriAI / litellm	15151
mediar-ai / screenpipe	11037
formbricks / formbricks	9386
anthropics / courses	8385
GreyDGL / PentestGPT	7374
superagent-ai / superagent	5391
promptfoo / promptfoo	4976
onlook-dev / onlook	4141
Canner / WrenAI	2526
pingcap / autoflow	2061
MLSysOps / MLE-agent	1161
open-webui / pipelines	1100
alishobeiri / thread	1074
topoteretes / cognee	971
bRAGAI / bRAG-langchain	823
opslane / opslane	677
dynamiq-ai / dynamiq	639
theopenconversationkit / tock	514
andysingal / llm-course	394
phospho-app / phospho	384
sentient-engineering / agent-q	370
sql-agi / DB-GPT	324
PostHog / posthog-foss	305
vespperhq / vespper	304
block / goose	295
aorwall / moatless-tools	291
dmayboroda / minima	221
RobotecAI / rai	172
i-am-alice / 3rd-devs	148
8090-inc / xrx-sample-apps	138
babelcloud / LLM-RGB	135
souzatharsis / tamingLLMs	129
LibreChat-AI / librechat.ai	128
deepset-ai / haystack-core-integrations	126

We take data security and privacy seriously. Please refer to our Security and Privacy page for more information.

By default, Langfuse automatically reports basic usage statistics of self-hosted instances to a centralized server (PostHog).

This helps us to:

1. Understand how Langfuse is used and improve the most relevant features.
2. Track overall usage for internal and external (e.g. fundraising) reporting.

None of the data is shared with third parties and does not include any sensitive information. We want to be super transparent about this and you can find the exact data we collect here.

You can opt-out by setting TELEMETRY_ENABLED=false.