Skip to main content
Clousight Bench 的追踪是 OpenTelemetry 原生的:经 OTel SDK 产生、用 OTel 语义约定标注、可经 OTLP 导出。一次评测运行 = 一条 trace。
Trace 是证据,不是判定:evaluator 不读它,基准指纹不含它,exporter 坏了也 永远不会让运行失败。

​
追踪覆盖

所有 span 共享该运行的 W3C trace_id(orchestrator 启动时预置),整次评测读作一棵树。

​
Trace 去哪

  1. 本地 JSONL(始终):<results>/traces/<trace_id>.jsonl —— 扁平 OTel span (hex id、纳秒时间、每行带 resource)。用 csbench trace list / csbench trace show <run-id> 查看。
  2. 套件轨迹 artifact:运行 artifacts 里的 trajectory.jsonl —— csbench serve 渲染为 waterfall(TPC 逐查询泳道、LLM 逐调用 span)。
  3. 你的 collector(可选):装 extra、指向 OTLP/HTTP ——
第三方 exporter 注册在 clousight_bench.span_exporters 入口点——契约就是 OTel SDK 的 SpanExporter,生态里任何 exporter 原样即插即用。

​
指标与日志信号

配同一个 CLOUSIGHT_OTLP_ENDPOINT(+ [otlp]),完成的运行还会发出:
  • metrics —— 每个数值测量一个 gauge(csbench.<key>,属性:unit、 reproducibility_class、official、该运行的 trace id);
  • logs —— 每个运行错误与 finding 一条记录,severity 已映射、与 trace 关联。
两者都是 finalize 时的一次性快照,且 fail-safe(遥测永远不会让运行失败)。endpoint 的值可以是 collector 基址,也可以是完整的 /v1/traces URL——各信号路径自动推导。

​
导入外部 OTel span

用标准 OTel 装配的 SUT(或任何工具)可以把自己的 span 交给 waterfall: csbench trace import <file> 接受 OTLP/JSON(resourceSpans)或扁平的 逐行 span JSONL,产出一份校验过的 v3 trajectory(--out 默认为 <file>.v3.jsonl)。没有语义约定判别键的 span 会得到一个诚实的 csbench.ingested 标记。

​
上下文传播(traceparent)

LLM-endpoint 调用携带 W3C traceparent 头。若被测服务自身有 OTel 装配(多数托管 网关都有),你的 APM 会看到这条 trace 延续进服务内部——评测过程与 SUT 内部视图 连成一条分布式链路,以记录中 extensions.core.trace_id 的同一 trace id 关联。

​
诚实边界

  • BenchBase（TPC-C）和 YCSB 是 Java 子进程:每次工具调用一个实测阶段 span (TPC-C:create+load+execute;YCSB:load 与 run),无内部 span。
  • TPC 官方 span 由实测区间重建(并发模型已知:阶段串行、流内查询背靠背)—— 计时忠实,但不是活体插桩。
  • 已部署的 agent-bundle 协议仍产 legacy v2 span;viewer 双读,新 span 源一律 v3 (OTel 原生)。