Langfuse

Deploy and configure Langfuse for LLM observability in CRAFT, traces, evaluations, and prompt management.

Langfuse

Langfuse is an LLM observability platform used by CRAFT to trace LLM calls, manage prompts, and run evaluations. CRAFT services are auto-instrumented to emit traces in the Langfuse format whenever a Langfuse host is configured.

Langfuse is optional. The platform operates normally without it. When configured, it enables LLM call tracing, evaluation, and prompt versioning. For the upstream Langfuse documentation, see langfuse.com/docs.

LLM Observability vs. Infrastructure Observability

	Langfuse	OpenTelemetry
Purpose	LLM call tracing, evaluation, cost	Infrastructure metrics, request traces, logs
What it instruments	LLM API calls (tokens, latency, cost, quality)	Application services (HTTP, DB, Redis)
Integration	LiteLLM callbacks plus @observe decorators on solution code paths	OTLP exporter
When active	LANGFUSE_HOST configured	OTEL_ENABLED=true

See LLM Observability for a conceptual overview of how these complement each other.

Auto-Enabled Integration

Langfuse is auto-enabled when LANGFUSE_HOST is set in any solution’s environment. The integration works through LiteLLM callbacks plus @observe decorators on key code paths. No code changes are needed in the solution services.

When enabled, Langfuse captures:

• Every LLM API call (model, prompt, completion, tokens, cost, latency)
• Agent session traces (multi-turn conversation flows)
• Evaluation results from scheduled and manual evaluations
• Prompt template versions and their usage

Cross-service tracing

Recent solution updates introduced a unified tracing model so a single user conversation produces a single, end-to-end trace, even when it crosses agent boundaries:

• Auto-instrumented entry points. Chat dispatch and the pipeline executor are decorated with @observe, so every conversation turn opens a trace span automatically.
• A2A trace context propagation. When one agent calls another via the A2A protocol, the trace context propagates through the A2A metadata so the receiving agent’s spans become children of the originating trace, not a new root.
• Deterministic trace IDs from turn_id. Trace IDs are seeded from the conversation turn ID. Reprocessing the same turn (e.g., a retried evaluation) emits to the same trace rather than creating a duplicate.
• Per-iteration spans inside agent loops. Multi-step agent loops emit one span per iteration so you can see how many planning steps a question took, how many tool calls each step made, and where time was spent.

The net effect: the Langfuse UI shows one trace per user question, regardless of how many services or LLM calls were involved.

Deployment

Langfuse is self-hosted. Choose the deployment model that fits your infrastructure.

Upstream Langfuse (Docker Compose)

For single-VM, demo, or local deployments, use the public upstream langfuse/langfuse Docker image:

# Get the upstream docker-compose.yml
curl -L -o docker-compose.yml https://raw.githubusercontent.com/langfuse/langfuse/main/docker-compose.yml

# Configure environment (see langfuse.com/docs for full reference)
# Required: NEXTAUTH_SECRET, SALT, database credentials

docker compose up -d

This starts the standard Langfuse stack: Web (Next.js), Worker, PostgreSQL, ClickHouse, Redis, and a blob store.

See langfuse.com/docs/deployment/self-host for the upstream self-hosting guide and configuration reference.

Kubernetes (Helm)

For production Kubernetes deployments, use the upstream Helm chart:

helm repo add langfuse https://langfuse.github.io/langfuse-k8s
helm install langfuse langfuse/langfuse \
  --namespace langfuse \
  --create-namespace \
  --set langfuse.nextauth.secret="<secret>" \
  --set langfuse.salt="<salt>" \
  --set postgresql.auth.password="<pg-password>"

See langfuse.com/docs/deployment/self-host/kubernetes for full Helm values.

Connecting CRAFT solutions to Langfuse

After deploying Langfuse (upstream or internal fork), configure each solution to send traces.

Data Insights (em-talk2data)

# Helm values or environment
em-talk2data:
  extraEnvVars:
    - name: LANGFUSE_HOST
      value: "https://langfuse.example.com"
    - name: LANGFUSE_PUBLIC_KEY
      valueFrom:
        secretKeyRef:
          name: langfuse-credentials
          key: public-key
    - name: LANGFUSE_SECRET_KEY
      valueFrom:
        secretKeyRef:
          name: langfuse-credentials
          key: secret-key

Data Governance (em-data-readiness)

Same environment variables: LANGFUSE_HOST, LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY.

Semiconductor (em-semi)

Same environment variables applied to the Backend API and AI Agent services.

Required Environment Variables

Variable	Description
LANGFUSE_HOST	URL of your Langfuse instance (e.g., https://langfuse.example.com)
LANGFUSE_PUBLIC_KEY	Project public key from Langfuse dashboard
LANGFUSE_SECRET_KEY	Project secret key from Langfuse dashboard

Accessing Langfuse

After deployment, access the Langfuse UI at your configured host URL.

1. Create an account or log in.
2. Create a project for each solution you want to trace.
3. Copy the Public Key and Secret Key from the project settings.
4. Configure these in the solution’s environment (see above).

Related

LLM Observability Overview

Why LLM observability matters and how Langfuse and OTel complement each other.

Langfuse Setup Guide

Step-by-step setup including all configuration options.

OpenTelemetry

Infrastructure-level observability (metrics, traces, logs).