JAiRouter 0.7.0 发布：一键开启 OpenTelemetry 分布式追踪，链路性能全掌握

---

1. 版本速览

JAiRouter 0.7.0 将 分布式追踪 从“可选项”升级为“即开即用”：

• 内置 OpenTelemetry SDK，零代码改动接入
• 支持 日志 / Jaeger / Zipkin / OTLP 四种导出器，生产&开发一键切换
• 提供 比率 / 规则 / 自适应 三种采样策略，性能与可观测性兼得
• 全链路异步导出 + 内存压力保护，P99 追踪延迟 < 0.5 ms

---

2. 一分钟跑起来

# application.yml
jairouter:
  tracing:
    enabled: true
    service-name: "jairouter"
    sampling:
      strategy: "ratio"
      ratio: 1.0          # 开发环境 100% 采样
    exporter:
      type: "logging"     # 先在控制台看效果

启动服务 → 发起任意请求 → 控制台立刻输出：

{
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "spanId": "00f067aa0ba902b7",
  "service": "jairouter",
  "duration": 150,
  "http.method": "POST",
  "http.url": "/api/v1/chat/completions"
}

---

3. 生产级配置模板

jairouter:
  tracing:
    enabled: true
    service-name: "jairouter-prod"
    environment: "production"
    sampling:
      strategy: "adaptive"
      adaptive:
        base-sample-rate: 0.01      # 1% 基础采样
        max-traces-per-second: 100  # 上限保护
        error-sample-rate: 1.0      # 错误全采
        slow-request-threshold: 3000
    exporter:
      type: "otlp"
      otlp:
        endpoint: "${OTLP_ENDPOINT}" # 复用现有 OpenTelemetry 收集器
        protocol: "grpc"
        compression: "gzip"
    memory:
      max-spans: 50000
      cleanup-interval: 30s
      span-ttl: 300s

---

4. 四大导出器，无缝对接现有体系

导出器	场景	配置片段
logging	本地调试	type: logging
jaeger	原生 Jaeger	type: jaeger endpoint: http://jaeger:14268/api/traces
zipkin	Zipkin 兼容	type: zipkin endpoint: http://zipkin:9411/api/v2/spans
otlp	通用 OpenTelemetry 后端	type: otlp endpoint: http://otel-collector:4317

---

5. 采样策略：性能与可观测性的平衡术

1. 比率采样——开发调试

   strategy: "ratio"
   ratio: 1.0
   

2. 规则采样——精准控制

   strategy: "rule"
   rules:
     - path-pattern: "/api/v1/chat/completions"
       sample-rate: 0.5
     - error-only: true
       sample-rate: 1.0
   

3. 自适应采样——生产推荐

   strategy: "adaptive"
   adaptive:
     base-sample-rate: 0.01
     max-traces-per-second: 100
     error-sample-rate: 1.0
     slow-request-threshold: 3000
   

---

6. 内置性能&内存保护

• 异步导出：批量 512 条/次，导出超时 10 s
• 内存上限：默认 50 k Span，TTL 5 min 自动清理
• GC 压力阈值：堆内存 > 70% 时主动降采样
• 突发保护：瞬时流量超过 max-traces-per-second 自动限流

---

7. 可观测性再升级：关键指标一键暴露

访问 http://localhost:8080/actuator/prometheus 即可抓取：

指标	含义
jairouter_tracing_spans_created_total	累计创建 Span 数
jairouter_tracing_spans_exported_total	累计导出 Span 数
jairouter_tracing_export_duration_seconds	导出耗时分布
jairouter_tracing_memory_used_ratio	内存使用比例

---

8. 升级注意事项

• 零侵入：无需改动业务代码，升级后默认关闭，手动 enabled: true 即可
• 配置收敛：追踪配置独立到 config/tracing/tracing-base.yml，支持 spring.config.import 覆盖
• 兼容 OpenTelemetry 1.32+：如已自建 otel-collector，直接复用 endpoint 与 headers

---

9. 下一步

• 快速开始 —— 3 分钟体验完整链路
• 配置参考 —— 全量参数速查表
• 运维指南 —— 生产部署、容量规划、告警模板
• 性能调优 —— 采样率、内存、JVM 调优最佳实践

---

GitHub 地址：https://github.com/Lincoln-cn/JAiRouter
文档中心：https://jairouter.com
问题反馈：https://github.com/Lincoln-cn/JAiRouter/issues