链路

分布式链路追踪是 Prom 和 Loki 之后的第三个 L1 后端。和它们一样，它遵循 ADR-014：edge 直推，manager 只查询。

数据面

text

your apps (OTLP gRPC/HTTP)
    │
    ▼
edge:
  otelcol (subprocess plugin)
    └─ remote OTLP → tempo:4317
                          │
                          ├─ trace storage (S3-compatible blob)
                          │
                          └─ metrics_generator → traces_spanmetrics_*
                                                       │
                                                       ▼
                                                 prometheus:9090

otelcol 在 edge agent 下作为插件跑（跟 promtail 同一种监管模型 —— 见日志）。collector 在主机上同时接受 gRPC（:4317）和 HTTP（:4318），批处理后通过 HTTPS 转给云端 Tempo。

应用不需要知道 Ongrid 存在

把应用的 OTel exporter 指向 http://localhost:4318（或对应的 gRPC）。本地 otelcol 处理认证 + 批处理 + 上云。删 Ongrid 等于删一个 env 变量 —— 你的代码不变。

spanmetrics 生成器

compose 里的 Tempo 部署启用了 metrics_generator。每批 span 产生三类派生指标并写回同一个 Prom：

Series	来源
`traces_spanmetrics_calls_total`	每个 (service, operation, status_code) 一个 counter
`traces_spanmetrics_latency_bucket`	span duration 的 histogram
`traces_spanmetrics_size_bucket`	可选，默认关

这是让 trace 告警感觉像指标告警的承重技巧：告警 evaluator 查 Prom，数据住在 Tempo。

告警类型

`trace_latency`

json

{
  "kind": "trace_latency",
  "scope_type": "global",
  "conditions_json": {
    "service": "payments-api",
    "operation": "POST /v1/charge",
    "quantile": "p95",
    "window": "5m",
    "threshold_ms": 800
  }
}

编译成：

promql

histogram_quantile(
  0.95,
  sum by (le) (rate(traces_spanmetrics_latency_bucket{
    service_name="payments-api", span_name="POST /v1/charge"
  }[5m]))
) * 1000 > 800

operation 可选 —— 不填就是服务级延迟。见 compileTraceLatencyRule。

支持的分位：p50 / p95（默认）/ p99。字符串形式存在是为了让 UI 表单选择器简洁；编译器映射到 histogram_quantile 要的浮点。

`trace_error_rate`

json

{
  "kind": "trace_error_rate",
  "scope_type": "global",
  "conditions_json": {
    "service": "payments-api",
    "window": "5m",
    "operator": ">",
    "threshold_pct": 1.0
  }
}

编译成：

promql

100 * (
  sum by (service_name) (rate(traces_spanmetrics_calls_total{
    service_name="payments-api", status_code="STATUS_CODE_ERROR"
  }[5m]))
  / sum by (service_name) (rate(traces_spanmetrics_calls_total{
    service_name="payments-api"
  }[5m]))
) > 1.0

STATUS_CODE_ERROR 字面量是 spanmetrics 生成器吐的；其他 span 状态约定需要自己的类型。

工具

`query_traceql`

直接透传到 Tempo 的 TraceQL endpoint （query_traceql_basetool.go）。当运维要具体的 trace ID 时 investigator persona 用 —— 比如 "找最近 30 分钟 payments-api 的一条慢 trace"。

text

{ resource.service.name="payments-api" } | duration > 800ms

底层 client 是 internal/pkg/tracequery；包名故意跟后端解耦 —— Jaeger / Zipkin client 可以以后塞进来，不用改 surface 名。

`correlate_incident`

investigator persona 开局调的复合工具。一次扇出调用拉到 incident 触发窗口附近的 Prom + Loki + Tempo 信号。把 4-5 次顺序 tool 调用压成一次 —— 在每次调查预算只有 10 次 tool 调用时这很重要。

见 correlate_incident_basetool.go。

另见

告警 —— 规则类型。
监控 —— trace 告警查的 Prom 后端。
拓扑 —— Tempo metrics_generator 自动推断的服务到服务边。
遥测数据面 —— ADR-014 全貌。

链路 ​

数据面 ​

spanmetrics 生成器 ​

告警类型 ​

trace_latency ​

trace_error_rate ​

工具 ​

query_traceql ​

correlate_incident ​

另见 ​

链路

数据面