AI 链路追踪

概述

AI 链路追踪模块基于 OpenTelemetry 手动 SDK 模式实现，记录工作流执行、LLM 调用、知识库检索等操作的链路信息，便于排查问题、统计用量和分析性能。

配置说明

application.yml

agent-plus:
  trace:
    # 是否开启链路追踪（关闭后 tracer 不初始化，span 埋点为空操作）
    enabled: true
    exporter:
      # 每批最大导出条数
      batch-size: 512
      # 定时导出间隔（毫秒）
      schedule-delay: 5000
      # 队列最大容量
      max-queue-size: 2048

核心概念

Span

链路追踪的基本单元，代表一次操作。

TraceId

一次完整执行的链路 ID，全局唯一。工作流执行时，traceId 等于 runId。

SpanId

单个 span 的 ID。

ParentSpanId

父 span 的 ID，用于构建父子关系。

数据库实体

AiTraceSpan（AI Trace Span记录）

字段	类型	说明
id	Long	自增主键
traceId	String	OTel 128-bit traceId(32hex)
spanId	String	OTel 64-bit spanId(16hex)
parentSpanId	String	父 spanId
spanName	String	span名称
spanKind	String	span类型：INTERNAL/SERVER/CLIENT/PRODUCER/CONSUMER
status	String	span状态：OK/ERROR
statusMessage	String	错误信息(仅status=ERROR时)
attributes	Map<String, Object>	span attribute键值对(含入参/出参等业务信息)
startTime	LocalDateTime	span开始时间(毫秒精度)
endTime	LocalDateTime	span结束时间(毫秒精度)
durationMs	Long	span耗时(毫秒)
orgId	Integer	组织ID
trialFlag	Integer	试运行标记：0-正式，1-试运行
createTime	LocalDateTime	记录创建时间

AiTraceSpanPayload（Span入参返回值载荷）

字段	类型	说明
id	Long	主键
traceId	String	traceId
spanId	String	spanId
inputPayload	String	节点入参(JSON)
outputPayload	String	节点返回值(JSON)
createTime	LocalDateTime	记录创建时间

埋点说明

@TraceSpan 注解

使用 @TraceSpan 注解标记需要追踪的方法：

@TraceSpan("llm.chat")
public AiChatResponse chat(AiChatRequest request) {
    // 方法体
}

手动创建 Span

Span span = TraceUtil.startSpan("operation.name");
try {
    // 业务逻辑
    TraceUtil.setAttributes(Map.of(
        "model", "qwen-plus",
        "prompt.tokens", 100,
        "completion.tokens", 50
    ));
    TraceUtil.setStatusOk();
} catch (Exception e) {
    TraceUtil.setStatusError(e.getMessage());
    throw e;
} finally {
    TraceUtil.endSpan();
}

追踪范围

当前已埋点的操作：

操作	Span 名称	说明
工作流执行	workflow.execute	工作流整体执行
节点执行	node.{type}.execute	单个节点执行
LLM 调用	llm.chat	LLM 调用
知识库检索	knowledge.retrieve	知识库检索
工具调用	tool.execute	工具执行

属性规范

LLM 调用 Span

属性名	说明
model	模型名称
prompt.tokens	Prompt Token 数
completion.tokens	Completion Token 数
total.tokens	总 Token 数

知识库检索 Span

属性名	说明
knowledge_base_id	知识库 ID
query	查询内容
top_k	返回数量
threshold	相似度阈值
result.count	命中数量

节点执行 Span

属性名	说明
node_id	节点 ID
node_type	节点类型

自动装配

TraceAutoConfiguration 自动配置：

• Tracer - OpenTelemetry Tracer
• SpanExporter - Span 导出器（默认 MySqlSpanExporter）
• TraceSpanAspect - @TraceSpan 注解 AOP 切面

核心类

TraceUtil

追踪工具类，提供静态方法：

• startSpan(String name) - 开始 span
• endSpan() - 结束 span
• setAttributes(Map<String, Object>) - 设置属性
• setStatusOk() - 设置状态为成功
• setStatusError(String message) - 设置状态为失败
• getCurrentTraceId() - 获取当前 traceId

MySqlSpanExporter

Span 导出器，将 span 写入 MySQL 表。

AI 日志表

除了链路追踪，系统还记录以下日志：

表名	说明
ai_llm_call_log	LLM 调用日志
ai_knowledge_retrieval_log	知识库检索日志
ai_knowledge_doc_log	文档处理日志

AI 用量统计

用量统计 模块