JAiRouter 完整链路追踪设计方案¶

一、概述¶

JAiRouter 作为 AI 模型服务网关，需要实现从用户请求/API入口开始的完整链路追踪，覆盖整个请求生命周期。

1.1 链路追踪流程¶

┌─────────────────────────────────────────────────────────────────────────────┐
│                           用户/API请求                                        │
└─────────────────────────────────────────────────────────────────────────────┘
                                    ↓
┌─────────────────────────────────────────────────────────────────────────────┐
│  TracingWebFilter                                                            │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │ 根Span: HTTP Server Request                                          │    │
│  │ - span.kind: SERVER                                                  │    │
│  │ - http.method, http.url, http.target                                 │    │
│  │ - traceparent 提取（如果有上游追踪）                                    │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────────┘
                                    ↓
┌─────────────────────────────────────────────────────────────────────────────┐
│  API Controller                                                              │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │ 子Span: routing                                                      │    │
│  │ - span.kind: INTERNAL                                                │    │
│  │ - routing.path, routing.service_type                                 │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────────┘
                                    ↓
┌─────────────────────────────────────────────────────────────────────────────┐
│  Service层 (路由、负载均衡、熔断、限流)                                         │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │ 子Span: gateway.process                                              │    │
│  │ - gateway.stage: routing/lb/cb/rl                                    │    │
│  │ - gateway.instance: 选中的实例信息                                     │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────────┘
                                    ↓
┌─────────────────────────────────────────────────────────────────────────────┐
│  Adapter层                                                                    │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │ 子Span: adapter.transform                                            │    │
│  │ - adapter.type: gpustack/ollama/vllm                                 │    │
│  │ - adapter.model: 模型名称                                             │    │
│  │ - adapter.operation: chat/embedding/rerank                           │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────────┘
                                    ↓
┌─────────────────────────────────────────────────────────────────────────────┐
│  WebClient 后端调用                                                           │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │ 子Span: backend.call                                                 │    │
│  │ - span.kind: CLIENT                                                  │    │
│  │ - backend.url, backend.instance                                      │    │
│  │ - 注入 traceparent 到请求头                                           │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────────┘
                                    ↓ [传播 Trace Context]
┌─────────────────────────────────────────────────────────────────────────────┐
│  后端模型服务 (GPUStack/Ollama/vLLM...)                                        │
│  └──────────────────────────────────────────────────────────────────────────┘
                                    ↓
┌─────────────────────────────────────────────────────────────────────────────┐
│  响应返回 → 完成所有Span → 记录到TraceQueryService                              │
└─────────────────────────────────────────────────────────────────────────────┘

1.2 Span 层级结构¶

层级	Span名称	SpanKind	属性
Level 0	`HTTP {method} {path}`	SERVER	http.method, http.url, http.target, http.status_code
Level 1	`gateway.process`	INTERNAL	gateway.stage, gateway.service_type
Level 2	`adapter.{type}.transform`	INTERNAL	adapter.type, adapter.model, adapter.operation
Level 3	`backend.{service}.call`	CLIENT	backend.url, backend.instance, backend.timeout

二、核心改进¶

2.1 Trace Context 传播机制¶

实现 W3C Trace Context 标准的完整传播：

// 请求头注入
traceparent: 00-{trace-id}-{parent-span-id}-{flags}
tracestate: key1=value1,key2=value2

// 响应头注入（可选）
traceresponse: 00-{trace-id}-{span-id}-{flags}

2.2 Span 父子关系管理¶

改进 Span 父子关系的计算和存储：

每个子 Span 记录 parentSpanId
支持多层级 Span 深度计算
Span 时间线可视化（甘特图）

2.3 数据持久化¶

将追踪数据持久化存储：

方案 A: Redis 存储（推荐）
方案 B: H2 数据库存储
方案 C: 外部追踪系统（Jaeger/Zipkin）

三、前端重构方案¶

3.1 功能模块整合¶

原 4 个功能模块 → 新 3 个功能模块

原模块	新模块	变化
追踪概览	追踪仪表盘	整合性能分析的关键指标
性能分析	追踪仪表盘	延迟/错误/吞吐量 Tab
追踪搜索	链路追踪	增强链路详情可视化
追踪管理	追踪配置	简化 UI 布局

3.2 新页面结构¶

/admin/tracing/
├── Dashboard.vue     # 追踪仪表盘（概览+性能分析）
├── Search.vue        # 链路追踪搜索
├── Management.vue    # 追踪配置管理
└── TraceDetail.vue   # 链路详情组件

四、实施计划¶

Phase 1: 后端增强（核心）¶

[ ] 增强 TracingService 子 Span 创建
[ ] 增强 BackendCallTracingInterceptor Trace Context 传播
[ ] 改进 TraceQueryService Span 关系计算
[ ] 实现 Redis 追踪数据存储

Phase 2: 前端重构¶

[ ] 整合 Dashboard.vue
[ ] 简化 Management.vue
[ ] 增强 Search.vue 链路详情

Phase 3: 测试验证¶

[ ] E2E 测试完整链路追踪
[ ] 前端功能验证

创建时间: 2026-04-10 版本: 1.0