跳转至

快速开始

文档版本: 1.0.0 最后更新: 2026-06-15 Git 提交: 933eeadf 作者: Lincoln

本指南将帮助您快速启用和配置 JAiRouter 的分布式追踪功能。

前提条件

  • Java 17 或更高版本
  • JAiRouter 服务已正常运行
  • 对 YAML 配置文件有基本了解

基础配置

1. 启用追踪功能

在 application.yml 中添加追踪配置：

jairouter:
  tracing:
    enabled: true
    service-name: "jairouter"
    service-version: "1.0.0"

2. 配置采样策略

jairouter:
  tracing:
    enabled: true
    service-name: "jairouter"
    sampling:
      strategy: "ratio"  # 可选值：ratio（默认）, rule, adaptive —— 见 config-reference（issue #234）
      ratio: 1.0         # 100% 采样（开发环境推荐）

3. 选择导出器

控制台日志导出（推荐用于开发）

jairouter:
  tracing:
    enabled: true
    service-name: "jairouter"
    exporter:
      type: "logging"

Jaeger 导出（推荐用于生产）

jairouter:
  tracing:
    enabled: true
    service-name: "jairouter"
    exporter:
      type: "jaeger"
      jaeger:
        endpoint: "http://localhost:14268/api/traces"

OTLP 导出（标准协议）

jairouter:
  tracing:
    enabled: true
    service-name: "jairouter"
    exporter:
      type: "otlp"
      otlp:
        # 核对（issue #159）：没有 protocol 这个旋钮（OtlpConfig 只有 endpoint /
        # timeout / headers / compression），OTLP 走 gRPC。
        endpoint: "http://localhost:4317"

验证配置

1. 启动服务

# 使用 Maven 启动
mvn spring-boot:run

# 或使用 Docker
docker-compose up

2. 检查追踪日志

启动后，您应该在控制台看到类似的追踪日志：

{
  "timestamp": "2024-01-15T10:30:15.123Z",
  "level": "INFO",
  "service": "jairouter",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "spanId": "00f067aa0ba902b7",
  "message": "Request processed successfully",
  "duration": 150,
  "http.method": "POST",
  "http.url": "/api/v1/chat/completions"
}

3. 发送测试请求

# 发送 API 请求
curl -X POST http://localhost:8080/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

4. 查看追踪数据

根据您配置的导出器类型：

日志导出

检查应用日志中的追踪信息：

# 查看最新的追踪日志
tail -f logs/application.log | grep traceId

Jaeger UI

打开浏览器访问 http://localhost:16686，搜索服务名称 "jairouter"。

OTLP 收集器

检查您的 OTEL 收集器配置和后端存储。

配置采样策略

比率采样（开发环境）

jairouter:
  tracing:
    sampling:
      # 采样策略（issue #234 起真实存在）：ratio 只按采样率，rule 按 rules 匹配，adaptive 需开启对应子配置。
      strategy: "ratio"
      ratio: 1.0  # 100% 采样，用于开发调试

规则采样（生产环境）

jairouter:
  tracing:
    sampling:
      # 规则采样要点：strategy 必须是 rule（issue #234）；规则的字段是 condition + ratio
      #（condition 是属性表达式，支持 >= / <= / == / !=，见 RuleBasedSamplingStrategy.matchesRule），
      # 原 service / operation / path-pattern / method / sample-rate 五个键都不存在。
      # 不匹配任何规则的请求走 sampling.ratio。
      rules:
        - condition: "http.status_code >= 500"                 # 错误请求：全采
          ratio: 1.0
        - condition: "http.route == /api/v1/chat/completions"  # 关键接口：50%
          ratio: 0.5

自适应采样（推荐）

jairouter:
  tracing:
    sampling:
      # 自适应采样要点（issue #234）：strategy 设为 adaptive 且 adaptive.enabled=true 才生效；
      # 原 max-traces-per-second / base-sample-rate / error-sample-rate 三个键都不存在。
      strategy: "adaptive"
      adaptive:
        enabled: true
        target-spans-per-second: 100  # 目标每秒 Span 数
        min-ratio: 0.1                # 采样率下限
        max-ratio: 1.0                # 采样率上限
        adjustment-interval: 30       # 调整间隔（秒）

性能调优

1. 异步导出配置

jairouter:
  tracing:
    # 核对（issue #224）：批处理器参数**不在** open-telemetry 段下（那里原有一套
    # sdk.trace.processors.batch.* 键，没有任何消费方，已删除），而在 performance 下。
    performance:
      batch:
        size: 100          # 最大导出一批的 Span 数
        timeout: 30s       # 导出超时（同时用作调度延迟）
      buffer:
        size: 2048         # 队列上限

2. 内存管理

jairouter:
  tracing:
    # 核对（issue #159）：真实路径是 performance.memory，且没有 cleanup-interval /
    # span-ttl 这两个旋钮（字段是 max-spans-in-memory / memory-limit-mb / gc-interval）。
    performance:
      memory:
        max-spans-in-memory: 10000
        memory-limit-mb: 100
        gc-interval: 60s

3. 采样率动态调整

生产环境建议从低采样率开始：

jairouter:
  tracing:
    sampling:
      adaptive:
        enabled: true
        target-spans-per-second: 50
        min-ratio: 0.01    # 1% 采样率下限
        max-ratio: 1.0

集成监控

1. 与 Prometheus 集成

追踪系统会自动暴露监控指标：

management:
  endpoints:
    web:
      exposure:
        include: "health,info,metrics,prometheus"
  metrics:
    export:
      prometheus:
        enabled: true

访问 http://localhost:8080/actuator/prometheus 查看追踪相关指标。

2. 关键指标

  • jairouter_tracing_spans_created_total - 创建的 Span 总数
  • jairouter_tracing_spans_exported_total - 导出的 Span 总数
  • jairouter_tracing_sampling_rate - 当前采样率
  • jairouter_tracing_export_duration - 导出耗时

常见问题

Q: 追踪数据没有导出

检查项目： 1. 确认 jairouter.tracing.enabled=true 2. 检查导出器配置是否正确 3. 验证网络连接（Jaeger/OTLP 端点） 4. 查看应用日志中的错误信息

Q: 性能影响过大

优化建议： 1. 降低采样率：sampling.ratio: 0.1 2. 启用异步导出 3. 调整批处理大小 4. 监控内存使用情况

Q: 追踪上下文丢失

排查步骤： 1. 检查异步操作是否正确传播上下文 2. 确认自定义过滤器的执行顺序 3. 验证 WebFlux 配置

下一步