Langfuse

LangFuse - Comprehensive AI observability and analytics for Drupal applications.

Built on the Dropsolid LangFuse PHP SDK (GitLab repo), this module integrates with LangFuse to provide detailed tracing, analytics, and insights for all your AI interactions in Drupal. Version 2.x sends traces over OpenTelemetry, so it works with Langfuse v4 and Langfuse Cloud, and records every conversation turn in a shape an LLM judge can evaluate.

Or, for more complex cases, when working with AI Agents that call other AI Agents, that themselves call a RAG tool:

Key Features

• Zero-configuration AI tracking: Automatically captures all AI.module interactions – programmatic, UI-based, and integrations.
• One trace per conversation turn: Embeddings, chat calls, tool calls and searches of a turn land in one trace, even when the chat polls across several requests.
• Conversations as sessions: Each chat thread or AI Answers conversation is one Langfuse session. Anonymous visitors get a stable pseudonym, so they are told apart without being identified.
• Ready for LLM-as-a-judge: Chat generations record the full message list, system prompt included, in the OpenAI chat format. The generation an evaluator should read is marked turn_final.
• Agent runs grouped: Each AI Agent run is one observation holding its model calls, tool calls and searches, nested correctly when agents call other agents.
• Filterable traces: Tags (search, index:…, agent:…, conversation:…, turn:…) and a small set of metadata on every observation.
• User feedback: Thumbs up/down buttons that record a user_feedback score on the trace.
• Comprehensive analytics: Token usage, response times, error rates, and model performance metrics in one place.
• Multiple authentication methods: API key pair (recommended), bearer token, basic auth, and full support for self-hosted LangFuse.
• Safe by default: Secrets in URL query strings are redacted, and a tracing failure is logged but never breaks the request it observes.

Quick Start

Which version

Langfuse v4 no longer accepts traces on the legacy ingestion endpoint that 1.0.x uses, and Langfuse Cloud turns it off on 16 November 2026. Check your server at https://your-langfuse-host/api/public/health.

Upgrading from 1.0.x? 2.x is a breaking release: payload shapes, metadata keys and sessions change. See "Upgrading from 1.x" in the README, and clear caches after updating.

Configuration

1. Go to /admin/config/system/langfuse/settings.
2. Enter your LangFuse URL, e.g. https://cloud.langfuse.com or your self-hosted URL.
3. Select an authentication method: API key pair (recommended), bearer token, or basic auth.
4. Enter credentials from your LangFuse project settings.
5. Save configuration. The connection is tested automatically.

How It Works

With the langfuse_ai_logging submodule enabled, AI.module interactions are logged automatically—no code changes required.

• Programmatic calls: any chat(), embeddings() or other operation on an AI provider.
• AI Explorer at /admin/config/ai/explorer.
• Any AI.module integration: AI Assistant chat, AI Answers, AI Search, embeddings, moderation, and more.

use Drupal\ai\OperationType\Chat\ChatInput;
use Drupal\ai\OperationType\Chat\ChatMessage;

// $providers is the ai.provider service, injected into your class.
$default = $providers->getDefaultProviderForOperationType('chat');
$input = new ChatInput([new ChatMessage('user', 'Explain quantum computing')]);

// Recorded in Langfuse as a trace with one chat generation.
$output = $providers->createInstance($default['provider_id'])
  ->chat($input, $default['model_id'], ['my_module']);

AI traces appear in your LangFuse project with full details: the message list and reply, timing, token usage, tool calls, agent runs, and nested spans for searches and embeddings. The README lists exactly what is recorded, the metadata keys and tags, and the privacy behaviour.

Module Architecture

Core Module (langfuse)

• LangFuse Client Service (langfuse.client): Main interface to the LangFuse SDK.
• Trace manager: Keeps one trace per conversation turn across requests, and links traces to users and sessions.
• Configuration management: Secure credential storage supporting multiple auth methods.
• Connection testing: Automatic validation of LangFuse connectivity from the UI.

AI.module Integration (langfuse_ai_logging)

• Event-driven architecture: Subscribes to AI.module pre/post generation events.
• Judge-ready payloads: Records generations as chat message lists and assistant replies with their tool calls.
• Zero developer effort: Works automatically with any AI.module integration.

AI Agents Logging (langfuse_ai_agents_logging)

Instrumentation specifically for the AI Agents module:

• Agent runs: Each run is one observation, with the task as input and the answer as output.
• Tool span tracking: Every tool execution becomes a LangFuse span under the reply that requested it.
• Delegation awareness: Nested agents sit inside the tool call that started them.
• Dependency isolation: Lives in its own submodule so sites not using AI Agents avoid the extra dependency.

AI Search Logging (langfuse_ai_search_logging)

Observability for Search API–based Retrieval-Augmented Generation (RAG) via search_api and ai_search:

• Search API events: Wraps search_api query pre/post execute to capture retrieval spans.
• Embedding parenting: Retrieval spans automatically become the parent of downstream embedding requests.
• Split motivation: Kept as a separate submodule so you don’t pull in search_api / ai_search unless you actually use them.

Feedback (langfuse_feedback)

• Thumbs up/down: Records a user_feedback score of 1 or 0 on the trace; a visitor's second vote replaces the first.
• Protected endpoint: CSRF token, permission and flood checks. Scores are not tied to the visitor who saw the answer, so treat them as visitor feedback, not authenticated evidence.

Example Implementation (langfuse_example)

• OpenAI demo form: Interactive example with chat completions.
• Manual trace management: Demonstrates creating and managing custom traces outside AI.module.