Salt 分布式追踪：用 OpenTelemetry 跟随一项作业-未完纪

Salt 可以为每次跨进程传递产生 OpenTelemetry span（跨度）。因此，salt '*' test.ping 这样的一项作业能形成一条分布式 trace，贯穿 CLI、master、minion、返回路径，以及中途可能出现的 reactor 或 syndic 转发。

实现使用标准 W3C TraceContext（traceparent / tracestate）传播上下文，通过 OTLP exporter 导出跨度。Jaeger 原生接收 OTLP；Tempo、Honeycomb、Datadog OTLP 等现代追踪后端也支持这种方式。

追踪上下文在 Salt 的 AES 加密消息封装内传播。线路上的攻击者无法看到追踪头；经过身份验证的 master、minion 和 syndic 在 AES 解密后读取它们。追踪默认关闭，未配置时完全不执行追踪工作：不创建跨度，不初始化 exporter，也不启动后台线程。

配置

在 master 和 minion 配置中添加 tracing 块。两个守护进程使用相同的配置块；它也适用于 salt-cli、salt-call、salt-api 和 salt-ssh。

tracing:
  enabled: true
  exporter: otlp-http            # otlp-http | otlp-grpc | console
  endpoint: ""                   # OTel SDK default endpoint when empty
  service_name: ""               # auto-derived when empty
  sampler: parent_based          # parent_based | always_on | always_off | trace_id_ratio
  sampler_arg: 1.0
  resource_attributes: {}
  insecure: true                 # gRPC TLS disabled (ignored for HTTP)
  headers: {}                    # OTLP authentication headers

enabled

总开关。为 false（默认值）时，模块中的所有追踪操作都是空操作。

exporter

otlp-http 是默认方式，以 HTTP/protobuf 将跨度发送到 endpoint。它是纯 Python 实现，包含在 Salt 基础依赖中；原文称其可用于所有解释器。otlp-grpc 使用 gRPC，需要另外安装 opentelemetry-exporter-otlp-proto-grpc。该包引入 grpcio，某些平台与解释器组合没有其预编译 wheel。console 将跨度打印到标准输出，用于调试。

endpoint

OTLP 收集器 URL。为空时使用 OTel SDK 默认端点：HTTP 为 http://localhost:4318/v1/traces，gRPC 为 http://localhost:4317。

service_name

资源属性 service.name。为空时 Salt 自动填入 salt-master、salt-minion-<id>、salt-cli、salt-call 或 salt-api。

sampler

选择安装在 TracerProvider 上的采样器：

parent_based（默认）遵循父跨度的采样决定，并对根跨度采样；将 sampler_arg 设为小于 1.0 的值，可以对根跨度按比例采样。
always_on 对每个跨度采样。
always_off 丢弃所有跨度，仅用于测试。
trace_id_ratio 对 sampler_arg 比例的 trace ID 采样。

resource_attributes

合并到 OTel Resource 的额外属性，例如 deployment.environment: prod。

insecure

关闭到收集器的 gRPC TLS。HTTP exporter 忽略这一设置。

headers

附加到每个 OTLP 请求的头，例如托管收集器使用的 Authorization: Bearer <token>。这是占位示例，不包含真实认证值。

覆盖的传递环节

一项 salt '*' test.ping 作业至少产生以下跨度：

salt.cli.test.ping：CLI 上的根跨度。
salt.req.send.publish：CLI → master 请求。
salt.req.recv.publish：master 收到请求。
salt.pub.send：master 发布作业。
salt.minion.recv.test.ping：minion 收到已发布的命令。
salt.minion.exec.test.ping：minion 执行函数。
salt.req.send._return：minion 向 master 返回。
salt.req.recv._return：master 收到返回。

此外，以下环节也设有追踪：

事件总线（fire_event / get_event）：每个 IPC 和 TCP-IPC 事件的数据字典携带追踪上下文。
Reactor：从传入事件提取上下文，正确设置反应跨度的父跨度。
Syndic 转发：既包括来自上游 master 的入站转发，也包括到下游 minion 的出站转发。
Salt-SSH：在远程 shim 上通过 TRACEPARENT 环境变量传递上下文。
Salt-API：从传入请求提取 traceparent HTTP 头；webhook 将上下文注入它触发的事件。

快速演示

启动一个 all-in-one Jaeger：

docker run -d --name jaeger \
  -p 16686:16686 -p 4318:4318 \
  jaegertracing/all-in-one:latest

给 master 与 minion 配置：

tracing:
  enabled: true
  exporter: otlp-http
  endpoint: http://localhost:4318/v1/traces
  sampler: always_on

启动二者，运行 salt '*' test.ping，访问 http://localhost:16686，搜索 salt-cli 服务。按照原文的演示预期，会看到一条追踪，其跨度分属 salt-cli、salt-master 和 salt-minion-<id> 三类服务。

fork 处理

OTel 的 BatchSpanProcessor 使用一个后台线程，该线程无法在 fork() 后继续工作。Salt 会在每个派生子进程第一次调用追踪 API 时重建 provider，因此 master 或 minion 启动的工作进程拥有可工作的 exporter，调用方不必额外处理。

fork 瞬间仍在父进程队列中且未刷出的跨度可能丢失。对于短生命周期跨度，这通常不明显；如果观察到缺口，可考虑使用 OTel 环境变量缩短 BatchSpanProcessor 队列相关时间间隔。

载荷开销

追踪启用且有正在记录的跨度时，每个 Salt 请求和事件大约增加 60 字节，即 W3C traceparent 字符串。没有正在记录的跨度时，例如请求处理器之外触发的内部周期事件，不附加追踪头。

演示边界

以上容器端口、明文 HTTP 端点与 always_on 是原文演示配置；应在获准的隔离环境中使用。远程 minion 的 localhost 指向该 minion 自身，需要按实际拓扑配置可达的收集器地址。本文没有运行 Salt、Docker 或收集器，也没有将原文的约 60 字节说明当作实测结果。