> ## Documentation Index
> Fetch the complete documentation index at: https://docs.emergence.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Langfuse
> Deploy and configure Langfuse for LLM observability in CRAFT, traces, evaluations, and prompt management.
# Langfuse
[Langfuse](https://langfuse.com) 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](https://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](/deployment/observability/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.
For single-VM, demo, or local deployments, use the public upstream `langfuse/langfuse` Docker image:
```bash theme={null}
# 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](https://langfuse.com/docs/deployment/self-host) for the upstream self-hosting guide and configuration reference.
For production Kubernetes deployments, use the upstream Helm chart:
```bash theme={null}
helm repo add langfuse https://langfuse.github.io/langfuse-k8s
helm install langfuse langfuse/langfuse \
--namespace langfuse \
--create-namespace \
--set langfuse.nextauth.secret="" \
--set langfuse.salt="" \
--set postgresql.auth.password=""
```
See [langfuse.com/docs/deployment/self-host/kubernetes](https://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)
```yaml theme={null}
# 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
Why LLM observability matters and how Langfuse and OTel complement each other.
Step-by-step setup including all configuration options.
Infrastructure-level observability (metrics, traces, logs).