""" Langfuse LLMOps Client - Phase 15.1 + 15.3 ========================================== LLM 呼叫追蹤、成本監控、Prompt 版本管理 Phase 15.1 (2026-03-26): 基礎整合 Phase 15.3 (2026-03-26): Deep Linking (Langfuse ↔ SignOz) 端點: http://192.168.0.110:3100 (DevOps 金庫) Features: - 自動追蹤所有 LLM 呼叫 (Ollama/Gemini/Claude) - 成本估算與監控 - Prompt 版本管理 - **Phase 15.3**: OTEL Trace 整合 (SignOz Deep Link) Usage: from src.services.langfuse_client import get_langfuse, langfuse_trace # 方法 1: Context Manager (自動整合 OTEL trace_id) async with langfuse_trace("openclaw_decision") as trace: result = await call_llm(prompt) trace.generation( name="ollama_call", model="qwen2.5:7b-instruct", input=prompt, output=result, ) # trace.metadata 自動包含 signoz_trace_url # 方法 2: 裝飾器 @langfuse_observe(name="analyze_incident") async def analyze_incident(incident_id: str): ... """ from collections.abc import Callable from contextlib import asynccontextmanager from functools import wraps from typing import Any import structlog from src.core.config import settings logger = structlog.get_logger(__name__) # Langfuse client singleton _langfuse_client = None def get_langfuse(): """ 取得 Langfuse client singleton Returns: Langfuse client 或 None (如果未啟用或未配置) """ global _langfuse_client if not settings.LANGFUSE_ENABLED: return None if not settings.LANGFUSE_PUBLIC_KEY or not settings.LANGFUSE_SECRET_KEY: logger.warning( "langfuse_not_configured", message="Langfuse enabled but keys not set", ) return None if _langfuse_client is None: try: from langfuse import Langfuse _langfuse_client = Langfuse( public_key=settings.LANGFUSE_PUBLIC_KEY, secret_key=settings.LANGFUSE_SECRET_KEY, host=settings.LANGFUSE_URL, ) logger.info( "langfuse_initialized", host=settings.LANGFUSE_URL, ) except Exception as e: logger.error( "langfuse_init_failed", error=str(e), ) return None return _langfuse_client class LangfuseTraceContext: """ Langfuse Trace Context for tracking LLM calls Phase 15.3: 自動整合 OTEL trace_id，實現 Langfuse ↔ SignOz Deep Linking """ def __init__(self, name: str, metadata: dict[str, Any] | None = None): self.name = name self.metadata = metadata or {} self.trace = None self._client = get_langfuse() self._otel_trace_id: str | None = None self._langfuse_trace_id: str | None = None def __enter__(self): if self._client: try: # Phase 15.3: 取得當前 OTEL trace_id 並注入 metadata from src.core.deep_linking import DeepLinking from src.core.telemetry import get_current_trace_id self._otel_trace_id = get_current_trace_id() # 建立含 SignOz Deep Link 的 metadata enriched_metadata = {**self.metadata} if self._otel_trace_id: enriched_metadata["otel_trace_id"] = self._otel_trace_id enriched_metadata["signoz_trace_url"] = DeepLinking.signoz_trace_url( self._otel_trace_id ) # 2026-04-02 Claude Code: 移除 v4.x 死碼分支 — SDK 已鎖定 <3.0.0 # v2.x API: client.trace() 建立追蹤 self.trace = self._client.trace( name=self.name, metadata=enriched_metadata, ) if self.trace: self._langfuse_trace_id = self.trace.id logger.debug( "langfuse_trace_started", name=self.name, otel_trace_id=self._otel_trace_id, langfuse_trace_id=self._langfuse_trace_id, ) except Exception as e: logger.warning("langfuse_trace_start_failed", error=str(e)) return self def __exit__(self, exc_type, exc_val, exc_tb): # Langfuse auto-flushes, no explicit close needed pass @property def otel_trace_id(self) -> str | None: """取得關聯的 OTEL trace_id""" return self._otel_trace_id @property def langfuse_trace_id(self) -> str | None: """取得 Langfuse trace_id""" return self._langfuse_trace_id def generation( self, name: str, model: str, input: str | dict[str, Any], output: str | dict[str, Any] | None = None, usage: dict[str, int] | None = None, metadata: dict[str, Any] | None = None, ): """ 記錄一次 LLM generation Args: name: Generation 名稱 (e.g., "ollama_call", "gemini_fallback") model: 模型名稱 (e.g., "qwen2.5:7b-instruct", "gemini-1.5-flash") input: 輸入 prompt output: 輸出結果 usage: Token 使用量 {"input": x, "output": y} metadata: 額外 metadata """ # Langfuse v4.x: trace 物件可能不存在，改用 logger 記錄 if self.trace and hasattr(self.trace, "generation"): try: gen = self.trace.generation( name=name, model=model, input=input, output=output, usage=usage, metadata=metadata or {}, ) return gen except Exception as e: logger.warning( "langfuse_generation_failed", error=str(e), name=name, model=model, ) return None else: # Langfuse v4.x: 透過 OTEL 追蹤，這裡只記錄 debug log logger.debug( "langfuse_generation_logged", name=name, model=model, trace_id=self._langfuse_trace_id, ) return None def span(self, name: str, metadata: dict[str, Any] | None = None): """ 記錄一個 span (非 LLM 操作) Args: name: Span 名稱 metadata: 額外 metadata """ if self.trace and hasattr(self.trace, "span"): try: return self.trace.span(name=name, metadata=metadata or {}) except Exception as e: logger.warning("langfuse_span_failed", error=str(e), name=name) return None else: # Langfuse v4.x: OTEL spans logger.debug("langfuse_span_logged", name=name, trace_id=self._langfuse_trace_id) return None def score( self, name: str, value: float, comment: str | None = None, ): """ 記錄評分 (用於 Prompt 品質追蹤) Args: name: 評分名稱 (e.g., "response_quality", "format_compliance") value: 分數 (0.0 - 1.0) comment: 評論 """ if self.trace and hasattr(self.trace, "score"): try: self.trace.score( name=name, value=value, comment=comment, ) except Exception as e: logger.warning( "langfuse_score_failed", error=str(e), name=name, ) else: # Langfuse v4.x: score via OTEL attributes logger.debug( "langfuse_score_logged", name=name, value=value, trace_id=self._langfuse_trace_id, ) def langfuse_trace(name: str, metadata: dict[str, Any] | None = None): """ Langfuse trace context manager Usage: with langfuse_trace("openclaw_decision") as trace: result = await call_llm(prompt) trace.generation(name="ollama", model="qwen2.5:7b-instruct", ...) """ return LangfuseTraceContext(name=name, metadata=metadata) @asynccontextmanager async def langfuse_trace_async(name: str, metadata: dict[str, Any] | None = None): """ Async version of langfuse_trace Usage: async with langfuse_trace_async("openclaw_decision") as trace: result = await call_llm(prompt) """ ctx = LangfuseTraceContext(name=name, metadata=metadata) ctx.__enter__() try: yield ctx finally: ctx.__exit__(None, None, None) def langfuse_observe( name: str | None = None, metadata: dict[str, Any] | None = None, ): """ Langfuse 裝飾器 - 自動追蹤函數執行 Usage: @langfuse_observe(name="analyze_incident") async def analyze_incident(incident_id: str): ... """ def decorator(func: Callable): trace_name = name or func.__name__ @wraps(func) async def async_wrapper(*args, **kwargs): async with langfuse_trace_async(trace_name, metadata) as trace: # Inject trace into kwargs if function accepts it if "langfuse_trace" in func.__code__.co_varnames: kwargs["langfuse_trace"] = trace return await func(*args, **kwargs) @wraps(func) def sync_wrapper(*args, **kwargs): with langfuse_trace(trace_name, metadata) as trace: if "langfuse_trace" in func.__code__.co_varnames: kwargs["langfuse_trace"] = trace return func(*args, **kwargs) # Return appropriate wrapper based on function type import asyncio if asyncio.iscoroutinefunction(func): return async_wrapper return sync_wrapper return decorator def flush_langfuse(): """ 手動 flush Langfuse (通常不需要，client 會自動 flush) 用於測試或確保資料送出 """ client = get_langfuse() if client: try: client.flush() logger.debug("langfuse_flushed") except Exception as e: logger.warning("langfuse_flush_failed", error=str(e))