配置参考¶

文档版本: 1.0.0 最后更新: 2026-06-02 Git 提交: b305e6de 作者: Lincoln

本文档提供 JAiRouter 分布式追踪功能的完整配置参考。

配置文件结构¶

JAiRouter 使用模块化的配置管理方式，追踪配置位于独立的配置文件中：

主配置文件: src/main/resources/application.yml
追踪配置文件: src/main/resources/config/tracing/tracing-base.yml
环境配置文件: src/main/resources/application-{profile}.yml

模块化配置说明¶

追踪配置已从主配置文件中分离，通过 spring.config.import 机制导入：

# application.yml
spring:
  config:
    import:
      - classpath:config/tracing/tracing-base.yml

权威来源：本页的键名以 src/main/resources/config/tracing/tracing-base.yml 为准 —— 那份文件有 TracingConfigBindingGuardTest 守着「键必须能绑到字段」。本页已于 issue #231 按代码逐条核对过键名/路径与"能力是否存在"，但仍有两类信息没有逐行复核（见文末「本页的已知缺口」）。
⚠️ 注意区分「键存在」与「调了有用」：tracing 配置里有一批字段能绑定但没有任何消费方 （issue #224 / #231 都在处理），本页已在相关小节就地标注。

基础配置¶

启用追踪¶

jairouter:
  tracing:
    enabled: true                    # 是否启用追踪功能，默认: true
    service-name: "jairouter"       # 服务名称，默认: "jairouter"
    service-version: "1.0.0"        # 服务版本，默认: "1.0.0"

基本配置项¶

配置项	类型	默认值	说明
`enabled`	boolean	`true`	是否启用追踪功能
`service-name`	string	`"jairouter"`	服务名称，用于标识追踪源
`service-version`	string	`"1.0.0"`	服务版本号
`service-namespace`	string	`"production"`	服务命名空间（原先这张表写的 `environment` 字段不存在，见 issue #231）

采样配置¶

比率采样¶

jairouter:
  tracing:
    sampling:
      # 采样策略（issue #234 起真实存在）：ratio（默认）/ rule / adaptive
      strategy: ratio
      ratio: 0.1                     # 采样率 0.0-1.0（字段默认 1.0，仓库 tracing-base.yml 配的是 0.1）

规则采样¶

jairouter:
  tracing:
    sampling:
      # 用规则采样需要把策略切到 rule（issue #234）；一条规则只有两个字段 —— condition 与 ratio。
      strategy: rule
      rules:
        - condition: "http.status_code >= 500"   # 属性表达式，支持 >= / <= / == / !=
          ratio: 1.0                             # 命中时按此采样率
        - condition: "http.route == /api/v1/chat/completions"
          ratio: 0.5

匹配语义（RuleBasedSamplingStrategy.matchesRule / SamplingConfigurationValidator.validateRuleCondition）：按 condition 里的比较运算符（>=、<=、==、!=）与 span 属性逐条比较，按声明顺序取第一条命中的规则； condition 里没有这些运算符会被判为疑似无效并给出告警。

接线情况（issue #234）：SamplingStrategyManager 会按 strategy 装配策略，选中 rule 时才把 RuleBasedSamplingStrategy 接进采样链 —— 也就是说只有把 strategy 设成 rule 时 rules 才生效；留在默认的 ratio 下，rules 不参与决策（这是有意的，避免"配了 rules 就悄悄改变全局采样率"）。同一策略下 always-sample / never-sample / service-ratios 也一并生效。
原先这张表（service / operation / path-pattern / method / header-name / header-value / error-only / status-code）八个条件在代码里都不存在，已删除。

自适应采样¶

jairouter:
  tracing:
    sampling:
      # 用自适应采样需要 strategy: adaptive 且 enabled: true（issue #234）
      strategy: adaptive
      adaptive:
        enabled: false                # 是否启用，默认: false
        target-spans-per-second: 1000 # 目标每秒 Span 数，默认: 1000
        min-ratio: 0.1                # 采样率下限，默认: 0.1
        max-ratio: 1.0                # 采样率上限，默认: 1.0
        adjustment-interval: 30       # 调整间隔（**整数秒**），默认: 30

接线情况（issue #234）：strategy: adaptive + adaptive.enabled: true 时， SamplingStrategyManager 会用上面这些字段构造 AdaptiveSamplingStrategy 并接进采样链；两者缺一时回落 ratio（并在启动日志与校验器里给出告警）。

导出器配置¶

日志导出器¶

jairouter:
  tracing:
    exporter:
      type: "logging"
      logging:
        # 核对（issue #231）：LoggingExporterConfig 只有 enabled / level 两个字段，
        # 原 format / include-resource 不存在，已删除。
        enabled: false               # 是否启用该导出器，默认: false
        level: "INFO"                # 日志级别，默认: INFO

Jaeger 导出器¶

jairouter:
  tracing:
    exporter:
      type: "jaeger"
      jaeger:
        endpoint: "http://localhost:14268/api/traces"  # Jaeger收集器端点
        timeout: 10s                 # 连接超时，默认: 10s
        # 核对（issue #231）：JaegerConfig 只有 endpoint / timeout / headers，没有 compression
        headers:                     # 自定义请求头
          "Authorization": "Bearer token"

Zipkin 导出器¶

jairouter:
  tracing:
    exporter:
      type: "zipkin"
      zipkin:
        endpoint: "http://localhost:9411/api/v2/spans"
        timeout: 10s
        # 核对（issue #231）：ZipkinConfig 只有 endpoint / timeout，没有 compression

OTLP 导出器¶

jairouter:
  tracing:
    exporter:
      type: "otlp"
      otlp:
        endpoint: "http://localhost:4317"  # OTLP端点（gRPC）
        timeout: 10s                 # 超时时间，默认: 10s
        compression: "gzip"          # 压缩方式
        headers:                     # 自定义头部
          "api-key": "your-api-key"
        # 核对（issue #231）：OtlpConfig 只有 endpoint / timeout / compression / headers，
        # 原 protocol 与整段 tls.* 都不存在，已删除。

批处理配置¶

jairouter:
  tracing:
    # 核对（issue #231）：批处理器参数**在 performance 下**，不是 open-telemetry 下。
    # 这里原先写的 open-telemetry.sdk.trace.processors.batch.* 确实能绑定，
    # 但没有任何生产代码读它 —— 与实际装配的键完全对不上，字段已在 #224 删除。
    # 真实装配见 OpenTelemetryAutoConfiguration#tracerProvider。
    performance:
      batch:
        size: 2048                   # 最大导出一批的 Span 数（setMaxExportBatchSize），默认: 100
        timeout: 30s                 # 导出超时（同时用作调度延迟），默认: 5s
      buffer:
        size: 8192                   # 队列上限（setMaxQueueSize 取的就是它），默认: 1024

内存管理配置¶

jairouter:
  tracing:
    performance:
      # 核对（issue #231）：真实路径是 performance.memory，且只有下面三个字段。
      # 原 max-spans / cleanup-interval / span-ttl / memory-threshold / gc-pressure-threshold
      # 以及整段 cache.* 都不存在，已删除。
      memory:
        max-spans-in-memory: 10000   # 内存中最大 Span 数量，默认: 10000
        memory-limit-mb: 100         # 内存上限(MB)，越过即触发回收，默认: 100
        gc-interval: 60s             # 内存压力检查间隔，默认: 60s

性能配置¶

jairouter:
  tracing:
    performance:
      async-processing: true       # 异步处理，默认: true
      # 异步处理线程池（issue #215：原文档写的 batch-size / buffer-size / max-queue-size
      # 在 performance 下都不是真实字段，照它配置不会生效）
      # 内存/性能监控两个调度器的上限（由构造器参数 @Value 读取，没有对应字段）
      scheduler:
        thread-cap: 2              # 线程上限，默认: 2
        queue-capacity: 100        # 队列上限，默认: 100

      thread-pool:
        core-size: 8               # boundedElastic 的 threadCap（即线程上限），默认: 2
        queue-capacity: 8192       # 队列上限，默认: 1000
        keep-alive: 60s            # 空闲线程存活时间（TTL），默认: 60s（#220 才接上消费方）
        thread-name-prefix: "tracing-"  # 线程名前缀，默认: "tracing-"
        # 注意：类里还有 max-size，但 boundedElastic 只有一个上限，它只被 /actuator/info 回显
      batch:
        size: 2048                 # 批大小，默认: 2048
        timeout: 30s               # 批超时，默认: 30s
        max-concurrent-batches: 3  # 同时进行的批次数上限，默认: 3
      buffer:
        size: 8192                 # 缓冲区大小，默认: 8192
        flush-interval: 5s         # 刷新间隔，默认: 5s
        max-wait-time: 30s         # 未攒满批次时最长再等多久，默认: 30s

组件配置¶

HTTP 配置¶

jairouter:
  tracing:
    components:
      http:
        enabled: true
        # 以下四个字段目前只被 /actuator/info 回显，不改变采集行为（issue #224）
        capture-headers: true
        capture-body: false
        excluded-paths: []

核对（issue #231 / #224）：原先这里的 WebFlux / WebClient / 数据库 / Redis 四段配置在 TracingComponentConfig 里都不存在（该类只有 http / load-balancer / rate-limiter / circuit-breaker；database / cache / messaging 三段因零消费方已在 #224 删除），已全部移除。

限流器配置¶

jairouter:
  tracing:
    components:
      rate-limiter:
        # enabled 是真正的行为开关（TracingWrapperFactory 读它）；capture-* 只被 /actuator/info 回显，
        # 调它们不改变行为（issue #224）。原 capture-quota / capture-decision 连回显都没有，已删除。
        enabled: true
        capture-algorithm: true
        capture-statistics: true

熔断器配置¶

jairouter:
  tracing:
    components:
      circuit-breaker:
        # 同上；原 capture-state-changes / capture-failure-rate 连回显都没有，已删除。
        enabled: true
        capture-state: true
        capture-statistics: true

负载均衡器配置¶

jairouter:
  tracing:
    components:
      load-balancer:
        # 同上；原 capture-selection 与 capture-candidates（后者连 yml 键都没有）已删除。
        enabled: true
        capture-strategy: true
        capture-statistics: true

安全配置¶

jairouter:
  tracing:
    security:
      # 整段开关（无字段、靠 @ConditionalOnProperty，缺省即开启）
      enabled: true
      sanitization:
        enabled: true
        inherit-global-rules: true
        additional-patterns: []
        sensitive-attributes: []      # 参与脱敏的属性名（#224 核对：真实字段）
      access-control:
        # 还有 access-control.enabled（条件键，无字段）；下面两项会回显到 /actuator/info
        restrict-trace-access: true
        allowed-roles: []
      # 核对（issue #231 / #224 批 B）：audit.* 整段（含 storage）以及 encryption 的
      # encrypt-sensitive-spans / encrypt-sensitive-logs / key-management.{rotation-interval,
      # key-store-path,use-hardware-security-module} / data-retention.* **零消费方，已删除**。
      # encryption 只剩 enabled / algorithm / key-size / key-management.auto-rotation，
      # 且它们仅被 /actuator/info 回显，故不在此登记。

监控配置¶

jairouter:
  tracing:
    monitoring:
      metrics:
        traces:
          histogram-buckets: [0.1, 0.5, 1.0, 2.0, 5.0, 10.0, 30.0]   # 处理延迟直方图桶边界，单位秒
      health:
        enabled: true
        check-interval: 30s          # 导出器健康检查周期（@Scheduled 也读它），默认: 30s
        failure-threshold: 3         # 连续失败多少次判不健康，默认: 3
        recovery-threshold: 2        # 连续成功多少次判恢复，默认: 2
      alerts:
        thresholds:
          memory-usage: 0.8          # 堆使用率超过该比例即判内存瓶颈，默认: 0.8
          export-latency-p99: 5000   # trace.export 操作的 P99 危险阈值(ms)，默认: 5000

health.{failure-threshold,recovery-threshold} 的语义是去抖动：ExporterHealthChecker 只在连续 failure-threshold 次检查失败后才把状态判为不健康，且只在连续recovery-threshold 次检查成功后恢复；中途出现相反结果会把对应的连续计数清零。因此单次抖动的检查结果不会翻转 /actuator/health 里的 exporterHealthChecker 组件。把阈值配成 1 即退化为「每次检查直接决定状态」。
核对（issue #231 / #224）：alerts 下的 trace-processing-failures / export-failures / buffer-pressure 三个键在 #215 已被删除（无对应字段）。metrics.exporter.*（4 个）、 metrics.enabled、metrics.prefix、metrics.traces.enabled、self-monitoring、alerts.enabled、 alerts.thresholds.export-failure-rate、alerts.thresholds.queue-size 在 #224 复核后确认 全仓没有任何读者（连 /actuator/info 都不回显 monitoring 段），键能绑定、文档却当真实旋钮宣传，属「绑定得上却永远不生效」，已一并删除。需要时请先实现消费方再加回来。
上面保留的 5 个键都有真实消费方：histogram-buckets → TracingPerformanceMonitor 注册 tracing.processing.latency 的直方图桶（注意单位是秒，而该指标以毫秒记录，装配时由消费方换算）； health.* → ExporterHealthChecker；alerts.thresholds.memory-usage 与 export-latency-p99 → TracingPerformanceMonitor#detectBottlenecks 与默认阈值表中的 trace.export（原先分别写死 0.8 / 5000）。

环境配置覆盖¶

不同环境可以通过对应的环境配置文件覆盖追踪配置：

开发环境 (application-dev.yml)¶

jairouter:
  tracing:
    enabled: true
    sampling:
      ratio: 1.0  # 开发环境100%采样

# 核对（issue #231）：tracing 段下没有 logging.level 字段，调试用 Spring 自己的日志级别
logging:
  level:
    org.unreal.modelrouter.monitor.tracing: DEBUG

生产环境 (application-prod.yml)¶

jairouter:
  tracing:
    enabled: true
    sampling:
      ratio: 0.1  # 生产环境10%采样
    exporter:
      type: "otlp"
      otlp:
        endpoint: "${OTLP_ENDPOINT:http://localhost:4317}"

最佳实践¶

配置管理¶

基础配置：在 tracing-base.yml 中定义通用配置
环境差异：在对应的环境配置文件中覆盖特定配置
敏感信息：使用环境变量注入敏感配置，如导出器端点、认证信息等

采样策略¶

开发环境：建议使用100%采样以便调试
生产环境：根据系统负载调整采样率，避免性能影响
关键路径：对重要业务使用规则采样确保追踪

性能优化¶

批处理：performance.batch.* 与 performance.buffer.size 同时决定导出批次行为，两者一起调
内存管理：performance.memory.memory-limit-mb 是回收的触发点，gc-interval 决定检查频率
组件选择：只有 components.{load-balancer,rate-limiter,circuit-breaker}.enabled 是真正生效的开关

本页的已知缺口（issue #231）¶

本页修的是键名/路径与能力是否存在这两类问题（原始清单见 issue #231）。以下内容尚未逐行复核：

各键在散文里描述的默认值：本页注明的是 config 类的字段默认值，而仓库的 tracing-base.yml 在若干键上另有取值（例如 sampling.ratio 类默认 1.0、yml 配 0.1），两者不一致时以你实际加载的配置文件为准；
告警示例（PromQL）、命令行与 curl 示例；
「最佳实践」一节属经验建议，不含可机械核对的事实。

另外，核对过程中发现两个能力层面的缺口（不是文档问题，已分别留痕）：

（sampling.rules / sampling.adaptive.* 已在 issue #234 接线：把 sampling.strategy 设为 rule / adaptive 即生效；security.audit.* 与 security.encryption.* 的零消费字段已在 issue #224 批 B 删除，不再出现在可配置面里。）