Skip to main content

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

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

LangfuseOpenTelemetry
PurposeLLM call tracing, evaluation, costInfrastructure metrics, request traces, logs
What it instrumentsLLM API calls (tokens, latency, cost, quality)Application services (HTTP, DB, Redis)
IntegrationLiteLLM callbacks plus @observe decorators on solution code pathsOTLP exporter
When activeLANGFUSE_HOST configuredOTEL_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.
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.

​
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

VariableDescription
LANGFUSE_HOSTURL of your Langfuse instance (e.g., https://langfuse.example.com)
LANGFUSE_PUBLIC_KEYProject public key from Langfuse dashboard
LANGFUSE_SECRET_KEYProject 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).

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).