feat: add langfuse doc

Author: zihenzzz

docs/ADVANCED_FEATURES-en.md

@@ -475,6 +475,83 @@ spring:
           timeout: 600000  # 10 minute timeout
 ```
 
+## Langfuse Observability
+
+DataAgent integrates [Langfuse](https://langfuse.com/) as an LLM observability platform, reporting trace data via the OpenTelemetry protocol to help you monitor and analyze agent performance.
+
+### Feature Overview
+
+- **Request Tracing**: Records the full lifecycle of each Graph stream processing (including new queries and human feedback)
+- **Token Usage Tracking**: Automatically accumulates prompt tokens and completion tokens per request
+- **Error Tracking**: Records exception types and error messages for troubleshooting
+- **Rich Metadata**: Records context attributes such as agentId, threadId, nl2sqlOnly, humanFeedback
+
+### Configuration
+
+Configure Langfuse connection in `application.yml`:
+
+```yaml
+spring:
+  ai:
+    alibaba:
+      data-agent:
+        langfuse:
+          enabled: ${LANGFUSE_ENABLED:true}
+          host: ${LANGFUSE_HOST:}
+          public-key: ${LANGFUSE_PUBLIC_KEY:}
+          secret-key: ${LANGFUSE_SECRET_KEY:}
+```
+
+Or configure via environment variables:
+
+```bash
+export LANGFUSE_ENABLED=true
+export LANGFUSE_HOST=https://cloud.langfuse.com
+export LANGFUSE_PUBLIC_KEY=pk-lf-xxx
+export LANGFUSE_SECRET_KEY=sk-lf-xxx
+```
+
+> For detailed configuration parameters, refer to [Developer Guide - Langfuse Configuration](DEVELOPER_GUIDE-en.md#11-langfuse-observability-configuration).
+
+### Technical Implementation
+
+The system sends trace data to Langfuse via OpenTelemetry OTLP HTTP protocol:
+
+```
+GraphServiceImpl
+    ├── startLLMSpan("graph-stream", request)    // New query starts
+    ├── startLLMSpan("graph-feedback", request)   // Human feedback starts
+    ├── FluxUtil.extractAndAccumulateTokens()      // Accumulate tokens during streaming
+    ├── endSpanSuccess(span, threadId, output)     // Success completion
+    └── endSpanError(span, threadId, exception)    // Error completion
+```
+
+### Span Attributes
+
+| Attribute | Description |
+|-----------|-------------|
+| `input.value` | Request input (JSON with query, agentId, threadId, etc.) |
+| `output.value` | Processing result |
+| `gen_ai.usage.prompt_tokens` | Accumulated prompt token count |
+| `gen_ai.usage.completion_tokens` | Accumulated completion token count |
+| `gen_ai.usage.total_tokens` | Total token count |
+| `data_agent.agent_id` | Agent ID |
+| `data_agent.thread_id` | Session thread ID |
+| `error.type` / `error.message` | Exception type and message (on failure only) |
+
+### Disabling Langfuse
+
+If observability is not needed, set `enabled` to `false`. The system will use a noop OpenTelemetry instance with zero performance overhead:
+
+```yaml
+spring:
+  ai:
+    alibaba:
+      data-agent:
+        langfuse:
+          enabled: false
+```
+
 ## Related Documents
 
 - [Quick Start](QUICK_START-en.md) - Basic configuration and installation

docs/ADVANCED_FEATURES.md

@@ -474,6 +474,59 @@ spring:
           timeout: 600000  # 10分钟超时
 ```
 
+## 📊 Langfuse 可观测性
+
+DataAgent 集成了 [Langfuse](https://langfuse.com/) 作为 LLM 可观测性平台，通过 OpenTelemetry 协议上报追踪数据，帮助您监控和分析智能体的运行状况。
+
+### 功能概述
+
+- **请求追踪**: 记录每次 Graph 流式处理的完整生命周期
+- **Token 用量统计**: 累计每次请求的 prompt tokens 和 completion tokens
+- **错误追踪**: 记录异常类型和错误信息，便于排查问题
+- 
+### 配置方式
+
+在 `application.yml` 中配置 Langfuse 连接信息：
+
+```yaml
+spring:
+  ai:
+    alibaba:
+      data-agent:
+        langfuse:
+          enabled: ${LANGFUSE_ENABLED:true}
+          host: ${LANGFUSE_HOST:}
+          public-key: ${LANGFUSE_PUBLIC_KEY:}
+          secret-key: ${LANGFUSE_SECRET_KEY:}
+```
+
+或通过环境变量配置：
+
+```bash
+export LANGFUSE_ENABLED=true
+export LANGFUSE_HOST=https://cloud.langfuse.com
+export LANGFUSE_PUBLIC_KEY=pk-lf-xxx
+export LANGFUSE_SECRET_KEY=sk-lf-xxx
+```
+
+> 配置参数详情请参考 [开发者指南 - Langfuse 配置](DEVELOPER_GUIDE.md#11-langfuse-可观测性配置-langfuse-observability)。
+
+
+
+
+### 禁用 Langfuse
+
+如不需要可观测性功能，设置 `enabled` 为 `false` 即可，系统将使用 noop OpenTelemetry 实例，不会产生任何性能开销：
+
+```yaml
+spring:
+  ai:
+    alibaba:
+      data-agent:
+        langfuse:
+          enabled: false
+```
+
 ## 📚 相关文档
 
 - [快速开始](QUICK_START.md) - 基础配置和安装

docs/ARCHITECTURE.md

@@ -34,6 +34,11 @@ flowchart LR
     Hybrid[HybridRetrievalStrategy]
     CodePool[CodePoolExecutorService]
     McpSvc[McpServerService]
+    LangfuseSvc[LangfuseService]
+  end
+
+  subgraph Observability[Observability]
+    Langfuse[Langfuse Platform]
   end
 
   subgraph Data[Data Storage]
@@ -78,6 +83,8 @@ flowchart LR
   CodePool --> Docker
   CodePool --> Local
   CodePool --> AISim
+  GraphSvc --> LangfuseSvc
+  LangfuseSvc --> Langfuse
   AgentCtl --> MetaDB
   PromptCtl --> MetaDB
   ModelCtl --> MetaDB
@@ -90,22 +97,25 @@ flowchart LR
   classDef data fill:#FEF3C7,stroke:#F59E0B,stroke-width:1px,color:#1F2937;
   classDef llm fill:#E0F7FA,stroke:#06B6D4,stroke-width:1px,color:#1F2937;
   classDef exec fill:#FFE4E6,stroke:#EF4444,stroke-width:1px,color:#1F2937;
+  classDef observability fill:#F3E8FF,stroke:#9333EA,stroke-width:1px,color:#1F2937;
 
   class UserUI,AdminUI,MCPClient client
   class RestAPI,SSE access
   class GraphCtl,AgentCtl,PromptCtl,ModelCtl api
-  class GraphSvc,Context,LlmSvc,ModelRegistry,VectorSvc,Hybrid,CodePool,McpSvc service
+  class GraphSvc,Context,LlmSvc,ModelRegistry,VectorSvc,Hybrid,CodePool,McpSvc,LangfuseSvc service
   class Graph workflow
   class BizDB,MetaDB,VectorDB,Files data
   class ChatLLM,EmbeddingLLM llm
   class Docker,Local,AISim exec
+  class Langfuse observability
 
   style Clients fill:#FFF7ED,stroke:#D97706,stroke-width:1.5px
   style Access fill:#EFF6FF,stroke:#0284C7,stroke-width:1.5px
   style Management fill:#F0FDF4,stroke:#16A34A,stroke-width:1.5px
   style Data fill:#FFFBEB,stroke:#F59E0B,stroke-width:1.5px
   style LLMs fill:#ECFEFF,stroke:#06B6D4,stroke-width:1.5px
   style Exec fill:#FFF1F2,stroke:#EF4444,stroke-width:1.5px
+  style Observability fill:#FAF5FF,stroke:#9333EA,stroke-width:1.5px
 ```
 
 ## 🔄 运行时主流程

docs/DEVELOPER_GUIDE-en.md

@@ -364,6 +364,21 @@ Configuration prefix: `spring.ai.alibaba.data-agent.report-template`
 | `marked-url` | Marked.js path (Markdown rendering library) | https://mirrors.sustech.edu.cn/cdnjs/ajax/libs/marked/12.0.0/marked.min.js |
 | `echarts-url` | ECharts path (chart library) | https://mirrors.sustech.edu.cn/cdnjs/ajax/libs/echarts/5.5.0/echarts.min.js |
 
+### 11. Langfuse Observability Configuration
+
+Configuration prefix: `spring.ai.alibaba.data-agent.langfuse`
+
+| Configuration Item | Description | Default Value |
+|-------------------|-------------|---------------|
+| `enabled` | Enable Langfuse observability | true |
+| `host` | Langfuse service URL (e.g. `https://cloud.langfuse.com` or self-hosted) | - |
+| `public-key` | Langfuse project Public Key | - |
+| `secret-key` | Langfuse project Secret Key | - |
+
+Environment variables: `LANGFUSE_ENABLED`, `LANGFUSE_HOST`, `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`
+
+> For detailed usage, refer to [Advanced Features - Langfuse Observability](ADVANCED_FEATURES-en.md#langfuse-observability).
+
 ## Learning Resources
 
 ### Official Documentation

docs/DEVELOPER_GUIDE.md

@@ -417,6 +417,21 @@ public class AgentVectorStoreService {
 | `marked-url` | Marked.js 路径 (Markdown渲染库) | https://mirrors.sustech.edu.cn/cdnjs/ajax/libs/marked/12.0.0/marked.min.js |
 | `echarts-url` | ECharts 路径 (图表库) | https://mirrors.sustech.edu.cn/cdnjs/ajax/libs/echarts/5.5.0/echarts.min.js |
 
+### 11. Langfuse 可观测性配置 (Langfuse Observability)
+
+配置前缀: `spring.ai.alibaba.data-agent.langfuse`
+
+| 配置项 | 说明 | 默认值 |
+|--------|------|--------|
+| `enabled` | 是否启用 Langfuse 可观测性 | true |
+| `host` | Langfuse 服务地址（如 `https://cloud.langfuse.com` 或自部署地址） | - |
+| `public-key` | Langfuse 项目的 Public Key | - |
+| `secret-key` | Langfuse 项目的 Secret Key | - |
+
+对应环境变量: `LANGFUSE_ENABLED`、`LANGFUSE_HOST`、`LANGFUSE_PUBLIC_KEY`、`LANGFUSE_SECRET_KEY`
+
+> 详细使用说明请参考 [高级功能 - Langfuse 可观测性](ADVANCED_FEATURES.md#-langfuse-可观测性)。
+
 ## 📚 学习资源
 
 ### 官方文档