add langfuse tracing

.env.example

@@ -100,6 +100,17 @@ TZ=Europe/Madrid
 # Get your API key from: https://platform.openai.com/api-keys
 OPENAI_API_KEY=your_openai_api_key_here
 
+# ============================================
+# LANGFUSE OBSERVABILITY
+# ============================================
+
+# Langfuse credentials for LLM tracing. Get keys from Langfuse UI -> Settings -> API Keys.
+# Leave blank to disable Langfuse tracing entirely.
+# Regions: EU=https://cloud.langfuse.com, US=https://us.cloud.langfuse.com
+LANGFUSE_PUBLIC_KEY=
+LANGFUSE_SECRET_KEY=
+LANGFUSE_BASE_URL=
+
 # ============================================
 # HUGGING FACE HUB (BUILD-TIME ONLY)
 # ============================================

README.md

@@ -91,6 +91,16 @@ cp .env.example .env
 | `LOGTO_MANAGEMENT_API_RESOURCE` | Resource opcional de la Management API de Logto |
 | `LOGTO_DEFAULT_USER_ROLE_ID` | Rol global opcional para auto-asignación de usuarios |
 
+#### Langfuse (Trazabilidad)
+
+Tracing opcional de las llamadas LLM y del grafo de LangGraph. Si las tres variables están vacías, el backend arranca con el tracing desactivado y no envía datos a Langfuse.
+
+| Variable | Descripción | Ejemplo |
+| --- | --- | --- |
+| `LANGFUSE_PUBLIC_KEY` | Clave pública del proyecto (Langfuse UI → Settings → API Keys) | `pk-lf-...` |
+| `LANGFUSE_SECRET_KEY` | Clave secreta del proyecto | `sk-lf-...` |
+| `LANGFUSE_BASE_URL` | Host de Langfuse. |  |
+
 #### Aplicación
 
 | Variable | Descripción | Default |

backend/pyproject.toml

@@ -63,6 +63,7 @@ dependencies = [
     "langchain-core==1.2.18",
     "langchain-openai==1.1.11",
     "langchain-text-splitters==1.1.1",
+    "langfuse>=4.0.0,<5.0.0",
     "langgraph==1.1.2",
     "langsmith==0.4.46",
     "logto==0.2.1",

backend/server.py

@@ -56,6 +56,7 @@
     top_k_topics,
 )
 from src.chat.store import ChatNotFoundError, ChatStore
+from src.tracing import get_langfuse_handler
 from src.utils.nlp import init_nlp
 from src.utils.rag import get_reranker, retrieve_and_rerank
 
@@ -428,7 +429,7 @@ async def _run_chat_turn(auth: AuthInfo, chat_id: str, query: str) -> dict[str,
 
     register_user_activity(questdb_pool)
 
-    config = {
+    config: dict[str, Any] = {
         "configurable": {
             "thread_id": chat_id,
             "vectorstore": app.state.vectorstore,
@@ -438,6 +439,17 @@ async def _run_chat_turn(auth: AuthInfo, chat_id: str, query: str) -> dict[str,
         }
     }
 
+    langfuse_handler = get_langfuse_handler()
+
+    if langfuse_handler is not None:
+        config["callbacks"] = [langfuse_handler]
+        config["run_name"] = "chat-turn"
+        config["metadata"] = {
+            "langfuse_user_id": auth.sub,
+            "langfuse_session_id": chat_id,
+            "langfuse_tags": ["asm2", "chat"],
+        }
+
     with TimedMetric(questdb_pool, Metrics.LLM_RESPONSE_TIME.value):
         try:
             result = await app.state.graph.ainvoke(

backend/src/tracing/__init__.py

@@ -0,0 +1,3 @@
+from .langfuse_setup import get_langfuse_handler
+
+__all__ = ["get_langfuse_handler"]

backend/src/tracing/langfuse_setup.py

@@ -0,0 +1,32 @@
+import logging
+import os
+from functools import lru_cache
+from typing import Any
+
+
+@lru_cache(maxsize=1)
+def get_langfuse_handler() -> Any | None:
+    public_key = os.getenv("LANGFUSE_PUBLIC_KEY")
+    secret_key = os.getenv("LANGFUSE_SECRET_KEY")
+    base_url = os.getenv("LANGFUSE_BASE_URL")
+
+    if not public_key or not secret_key or not base_url:
+        logging.info("Langfuse credentials not set; tracing disabled")
+        return None
+
+    try:
+        from langfuse import Langfuse
+        from langfuse.langchain import CallbackHandler
+
+        Langfuse(
+            public_key=public_key,
+            secret_key=secret_key,
+            host=base_url,
+        )
+        logging.info("Langfuse tracing enabled (host=%s)", base_url)
+
+        return CallbackHandler()
+
+    except Exception:
+        logging.warning("Failed to initialize Langfuse; tracing disabled", exc_info=True)
+        return None