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