feat(tracing): add optional Langfuse support (#1717)

* feat(tracing): add optional Langfuse support

* Fix tracing fail-fast behavior for explicitly enabled providers

* fix(lint)

backend/packages/harness/deerflow/config/__init__.py

@@ -3,7 +3,13 @@ from .extensions_config import ExtensionsConfig, get_extensions_config
 from .memory_config import MemoryConfig, get_memory_config
 from .paths import Paths, get_paths
 from .skills_config import SkillsConfig
-from .tracing_config import get_tracing_config, is_tracing_enabled
+from .tracing_config import (
+    get_enabled_tracing_providers,
+    get_explicitly_enabled_tracing_providers,
+    get_tracing_config,
+    is_tracing_enabled,
+    validate_enabled_tracing_providers,
+)
 
 __all__ = [
     "get_app_config",
@@ -15,5 +21,8 @@ __all__ = [
     "MemoryConfig",
     "get_memory_config",
     "get_tracing_config",
+    "get_explicitly_enabled_tracing_providers",
+    "get_enabled_tracing_providers",
     "is_tracing_enabled",
+    "validate_enabled_tracing_providers",
 ]

backend/packages/harness/deerflow/config/tracing_config.py

@@ -1,14 +1,12 @@
-import logging
 import os
 import threading
 
 from pydantic import BaseModel, Field
 
-logger = logging.getLogger(__name__)
 _config_lock = threading.Lock()
 
 
-class TracingConfig(BaseModel):
+class LangSmithTracingConfig(BaseModel):
     """Configuration for LangSmith tracing."""
 
     enabled: bool = Field(...)
@@ -18,9 +16,69 @@ class TracingConfig(BaseModel):
 
     @property
     def is_configured(self) -> bool:
-        """Check if tracing is fully configured (enabled and has API key)."""
         return self.enabled and bool(self.api_key)
 
+    def validate(self) -> None:
+        if self.enabled and not self.api_key:
+            raise ValueError("LangSmith tracing is enabled but LANGSMITH_API_KEY (or LANGCHAIN_API_KEY) is not set.")
+
+
+class LangfuseTracingConfig(BaseModel):
+    """Configuration for Langfuse tracing."""
+
+    enabled: bool = Field(...)
+    public_key: str | None = Field(...)
+    secret_key: str | None = Field(...)
+    host: str = Field(...)
+
+    @property
+    def is_configured(self) -> bool:
+        return self.enabled and bool(self.public_key) and bool(self.secret_key)
+
+    def validate(self) -> None:
+        if not self.enabled:
+            return
+        missing: list[str] = []
+        if not self.public_key:
+            missing.append("LANGFUSE_PUBLIC_KEY")
+        if not self.secret_key:
+            missing.append("LANGFUSE_SECRET_KEY")
+        if missing:
+            raise ValueError(f"Langfuse tracing is enabled but required settings are missing: {', '.join(missing)}")
+
+
+class TracingConfig(BaseModel):
+    """Tracing configuration for supported providers."""
+
+    langsmith: LangSmithTracingConfig = Field(...)
+    langfuse: LangfuseTracingConfig = Field(...)
+
+    @property
+    def is_configured(self) -> bool:
+        return bool(self.enabled_providers)
+
+    @property
+    def explicitly_enabled_providers(self) -> list[str]:
+        enabled: list[str] = []
+        if self.langsmith.enabled:
+            enabled.append("langsmith")
+        if self.langfuse.enabled:
+            enabled.append("langfuse")
+        return enabled
+
+    @property
+    def enabled_providers(self) -> list[str]:
+        enabled: list[str] = []
+        if self.langsmith.is_configured:
+            enabled.append("langsmith")
+        if self.langfuse.is_configured:
+            enabled.append("langfuse")
+        return enabled
+
+    def validate_enabled(self) -> None:
+        self.langsmith.validate()
+        self.langfuse.validate()
+
 
 _tracing_config: TracingConfig | None = None
 
@@ -29,12 +87,7 @@ _TRUTHY_VALUES = {"1", "true", "yes", "on"}
 
 
 def _env_flag_preferred(*names: str) -> bool:
-    """Return the boolean value of the first env var that is present and non-empty.
-
-    Accepted truthy values (case-insensitive): ``1``, ``true``, ``yes``, ``on``.
-    Any other non-empty value is treated as falsy.  If none of the named
-    variables is set, returns ``False``.
-    """
+    """Return the boolean value of the first env var that is present and non-empty."""
     for name in names:
         value = os.environ.get(name)
         if value is not None and value.strip():
@@ -52,43 +105,45 @@ def _first_env_value(*names: str) -> str | None:
 
 
 def get_tracing_config() -> TracingConfig:
-    """Get the current tracing configuration from environment variables.
-
-    ``LANGSMITH_*`` variables take precedence over their legacy ``LANGCHAIN_*``
-    counterparts.  For boolean flags (``enabled``), the *first* variable that is
-    present and non-empty in the priority list is the sole authority – its value
-    is parsed and returned without consulting the remaining candidates.  Accepted
-    truthy values are ``1``, ``true``, ``yes``, and ``on`` (case-insensitive);
-    any other non-empty value is treated as falsy.
-
-    Priority order:
-        enabled  : LANGSMITH_TRACING > LANGCHAIN_TRACING_V2 > LANGCHAIN_TRACING
-        api_key  : LANGSMITH_API_KEY  > LANGCHAIN_API_KEY
-        project  : LANGSMITH_PROJECT  > LANGCHAIN_PROJECT   (default: "deer-flow")
-        endpoint : LANGSMITH_ENDPOINT > LANGCHAIN_ENDPOINT  (default: https://api.smith.langchain.com)
-
-    Returns:
-        TracingConfig with current settings.
-    """
+    """Get the current tracing configuration from environment variables."""
     global _tracing_config
     if _tracing_config is not None:
         return _tracing_config
     with _config_lock:
-        if _tracing_config is not None:  # Double-check after acquiring lock
+        if _tracing_config is not None:
             return _tracing_config
         _tracing_config = TracingConfig(
-            # Keep compatibility with both legacy LANGCHAIN_* and newer LANGSMITH_* variables.
-            enabled=_env_flag_preferred("LANGSMITH_TRACING", "LANGCHAIN_TRACING_V2", "LANGCHAIN_TRACING"),
-            api_key=_first_env_value("LANGSMITH_API_KEY", "LANGCHAIN_API_KEY"),
-            project=_first_env_value("LANGSMITH_PROJECT", "LANGCHAIN_PROJECT") or "deer-flow",
-            endpoint=_first_env_value("LANGSMITH_ENDPOINT", "LANGCHAIN_ENDPOINT") or "https://api.smith.langchain.com",
+            langsmith=LangSmithTracingConfig(
+                enabled=_env_flag_preferred("LANGSMITH_TRACING", "LANGCHAIN_TRACING_V2", "LANGCHAIN_TRACING"),
+                api_key=_first_env_value("LANGSMITH_API_KEY", "LANGCHAIN_API_KEY"),
+                project=_first_env_value("LANGSMITH_PROJECT", "LANGCHAIN_PROJECT") or "deer-flow",
+                endpoint=_first_env_value("LANGSMITH_ENDPOINT", "LANGCHAIN_ENDPOINT") or "https://api.smith.langchain.com",
+            ),
+            langfuse=LangfuseTracingConfig(
+                enabled=_env_flag_preferred("LANGFUSE_TRACING"),
+                public_key=_first_env_value("LANGFUSE_PUBLIC_KEY"),
+                secret_key=_first_env_value("LANGFUSE_SECRET_KEY"),
+                host=_first_env_value("LANGFUSE_BASE_URL") or "https://cloud.langfuse.com",
+            ),
         )
         return _tracing_config
 
 
+def get_enabled_tracing_providers() -> list[str]:
+    """Return the configured tracing providers that are enabled and complete."""
+    return get_tracing_config().enabled_providers
+
+
+def get_explicitly_enabled_tracing_providers() -> list[str]:
+    """Return tracing providers explicitly enabled by config, even if incomplete."""
+    return get_tracing_config().explicitly_enabled_providers
+
+
+def validate_enabled_tracing_providers() -> None:
+    """Validate that any explicitly enabled providers are fully configured."""
+    get_tracing_config().validate_enabled()
+
+
 def is_tracing_enabled() -> bool:
-    """Check if LangSmith tracing is enabled and configured.
-    Returns:
-        True if tracing is enabled and has an API key.
-    """
+    """Check if any tracing provider is enabled and fully configured."""
     return get_tracing_config().is_configured

backend/packages/harness/deerflow/models/factory.py

@@ -2,8 +2,9 @@ import logging
 
 from langchain.chat_models import BaseChatModel
 
-from deerflow.config import get_app_config, get_tracing_config, is_tracing_enabled
+from deerflow.config import get_app_config
 from deerflow.reflection import resolve_class
+from deerflow.tracing import build_tracing_callbacks
 
 logger = logging.getLogger(__name__)
 
@@ -79,17 +80,9 @@ def create_chat_model(name: str | None = None, thinking_enabled: bool = False, *
 
     model_instance = model_class(**kwargs, **model_settings_from_config)
 
-    if is_tracing_enabled():
-        try:
-            from langchain_core.tracers.langchain import LangChainTracer
-
-            tracing_config = get_tracing_config()
-            tracer = LangChainTracer(
-                project_name=tracing_config.project,
-            )
-            existing_callbacks = model_instance.callbacks or []
-            model_instance.callbacks = [*existing_callbacks, tracer]
-            logger.debug(f"LangSmith tracing attached to model '{name}' (project='{tracing_config.project}')")
-        except Exception as e:
-            logger.warning(f"Failed to attach LangSmith tracing to model '{name}': {e}")
+    callbacks = build_tracing_callbacks()
+    if callbacks:
+        existing_callbacks = model_instance.callbacks or []
+        model_instance.callbacks = [*existing_callbacks, *callbacks]
+        logger.debug(f"Tracing attached to model '{name}' with providers={len(callbacks)}")
     return model_instance

backend/packages/harness/deerflow/tracing/__init__.py

@@ -0,0 +1,3 @@
+from .factory import build_tracing_callbacks
+
+__all__ = ["build_tracing_callbacks"]

backend/packages/harness/deerflow/tracing/factory.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import Any
+
+from deerflow.config import (
+    get_enabled_tracing_providers,
+    get_tracing_config,
+    validate_enabled_tracing_providers,
+)
+
+
+def _create_langsmith_tracer(config) -> Any:
+    from langchain_core.tracers.langchain import LangChainTracer
+
+    return LangChainTracer(project_name=config.project)
+
+
+def _create_langfuse_handler(config) -> Any:
+    from langfuse import Langfuse
+    from langfuse.langchain import CallbackHandler as LangfuseCallbackHandler
+
+    # langfuse>=4 initializes project-specific credentials through the client
+    # singleton; the LangChain callback then attaches to that configured client.
+    Langfuse(
+        secret_key=config.secret_key,
+        public_key=config.public_key,
+        host=config.host,
+    )
+    return LangfuseCallbackHandler(public_key=config.public_key)
+
+
+def build_tracing_callbacks() -> list[Any]:
+    """Build callbacks for all explicitly enabled tracing providers."""
+    validate_enabled_tracing_providers()
+    enabled_providers = get_enabled_tracing_providers()
+    if not enabled_providers:
+        return []
+
+    tracing_config = get_tracing_config()
+    callbacks: list[Any] = []
+
+    for provider in enabled_providers:
+        if provider == "langsmith":
+            try:
+                callbacks.append(_create_langsmith_tracer(tracing_config.langsmith))
+            except Exception as exc:  # pragma: no cover - exercised via tests with monkeypatch
+                raise RuntimeError(f"LangSmith tracing initialization failed: {exc}") from exc
+        elif provider == "langfuse":
+            try:
+                callbacks.append(_create_langfuse_handler(tracing_config.langfuse))
+            except Exception as exc:  # pragma: no cover - exercised via tests with monkeypatch
+                raise RuntimeError(f"Langfuse tracing initialization failed: {exc}") from exc
+
+    return callbacks

backend/packages/harness/pyproject.toml

@@ -14,6 +14,7 @@ dependencies = [
     "langchain-deepseek>=1.0.1",
     "langchain-mcp-adapters>=0.1.0",
     "langchain-openai>=1.1.7",
+    "langfuse>=3.4.1",
     "langgraph>=1.0.6,<1.0.10",
     "langgraph-api>=0.7.0,<0.8.0",
     "langgraph-cli>=0.4.14",