追踪 · XB 现场笔记

Baggage 通过明确的边界传播上下文

Mon, 27 Mar 2028 00:00:00 +0000

OpenTelemetry 的 Baggage 是与上下文关联的一组字符串键值，可以让请求入口已经知道的信息继续到达下游，例如部署区域或发布分组。它与跨度属性不同，主要用途是传播；它也与链路上下文不同，承载的是应用选择的信息，而不是连接跨度的身份标识和标志。这些机制可以一起出现在一个请求里，但不能因此把它们理解为同一份数据，也不能假定它们具有相同的存储和信任语义。

跨进程传播必须落实到具体边界。发送客户端把上下文注入 HTTP 请求头等载体，接收端再从载体中提取成本地上下文。配置正确的插桩库可以自动执行这些动作，手工插桩时则要明确调用。仅在一个进程中创建行李字段，并不会把信息自动送到另一个进程、任意后台任务或外部服务。判断传播是否成功，应检查真实客户端与接收端，而不是只检查入口是否调用过设置函数。

决定哪些信息可以传播、哪些需要记录

行李字段不会自动成为跨度、日志或指标的属性。下游必须显式读取并复制，或者使用配置好的处理器执行这一映射策略。团队如果只打开传播，就期待在查询后台找到对应属性，通常会遇到数据看似消失的问题。反过来，把所有入站字段无差别复制进遥测，也可能造成语义不清、数据过大或指标基数增长。传播和记录是两个独立决定，应当分别明确目的与范围。

上下文操作返回新的上下文，不会把所有既有引用同时修改。调用者需要保留返回值，并在预期的位置传递或附加它。为某个出站请求删除不合适的行李字段时，也应保留该请求仍然需要的链路上下文。出站字段允许列表和遥测属性允许列表都应当是明确策略：某个接收者需要的值，不一定适合随后经过的全部目的地，更不一定适合永久写入所有观测记录。

坏掉的样子

行李上下文本身没有内置机制，能够证明某个值确实由可信组件签发。调用方完全可以提交请求头，自称属于昂贵账户等级或拥有特权角色。解析成功只能说明数据表示可被读取，不能说明其声明具有授权效力。认证与权限判断必须依赖各自可信的输入。即使字段很短、内容看起来合理，也不能跳过信任来源判断；本地解析器接受字符串，不等于业务系统应该接受其中的身份声明。

不受限制的行李字段会增加请求头大小，也可能把敏感信息传播给原本不该接收它的对象，包括自动插桩所覆盖的第三方接口。需要限制键名与值的范围，检查实际传播目的地，并由传播器负责线上编码。两个相同 SDK 实例之间往返成功，也不等于所有语言实现和代理组合都能够互操作。真正跨服务使用时，应验证实际途经的边界，而不是把一个进程内的演示扩大成对整个部署的保证。

Baggage 传播与信任：机制与证据边界。

快速验证

建立 Python 虚拟环境，安装 opentelemetry-sdk==1.35.0，把脚本保存为 baggage.py，并使用该环境的解释器运行。作者曾报告 Python 3.14.4 运行；保留的精确记录覆盖 Python 3.12.14 与 SDK 1.35.0。本轮源码复核没有重跑。实验调用真实的 W3C 链路上下文传播器和行李传播器，并把跨度导出到内存；显式始终采样避免继承的采样设置影响结果。须启用断言，不使用 -O 或 PYTHONOPTIMIZE；force_flush 调用本身位于 assert 内。没有启动 HTTP 服务，字典代表客户端接下来将发送的请求头载体。因此结果直接证明编解码与上下文行为，不把尚未执行的跨服务通信写成已完成验证。

import json

from opentelemetry import baggage, trace
from opentelemetry.context import Context
from opentelemetry.baggage.propagation import W3CBaggagePropagator
from opentelemetry.propagators.composite import CompositePropagator
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.sampling import ALWAYS_ON
from opentelemetry.sdk.trace.export import SimpleSpanProcessor
from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator

base = Context()
raw = baggage.set_baggage("region", "eu-west", context=base)
raw = baggage.set_baggage("release", "canary/2", context=raw)
raw = baggage.set_baggage("internal_note", "synthetic-only", context=raw)
assert not baggage.get_all(base)
propagator = CompositePropagator([TraceContextTextMapPropagator(), W3CBaggagePropagator()])
provider = TracerProvider(sampler=ALWAYS_ON)
exporter = InMemorySpanExporter()
provider.add_span_processor(SimpleSpanProcessor(exporter))
tracer = provider.get_tracer("baggage-lab")
with tracer.start_as_current_span("parent", context=Context()) as parent:
 outgoing = trace.set_span_in_context(parent, baggage.clear(context=raw))
 for key in ("region", "release"):
 outgoing = baggage.set_baggage(key, baggage.get_baggage(key, raw), context=outgoing)
 carrier = {}
 propagator.inject(carrier, context=outgoing)
 received = propagator.extract(carrier, context=Context())
 assert set(baggage.get_all(received)) == {"region", "release"}
 assert baggage.get_baggage("region", received) == "eu-west"
 assert baggage.get_baggage("release", received) == "canary/2"
 assert baggage.get_baggage("internal_note", raw) == "synthetic-only"
 assert trace.get_current_span(received).get_span_context().trace_id == parent.get_span_context().trace_id
 with tracer.start_as_current_span("inherited", context=received):
 pass
 with tracer.start_as_current_span("copied", context=received) as span:
 span.set_attribute("deployment.region", baggage.get_baggage("region", received))
assert provider.force_flush()
spans = {span.name: span for span in exporter.get_finished_spans()}
assert not spans["inherited"].attributes
assert spans["copied"].attributes == {"deployment.region": "eu-west"}
independent = propagator.extract({"traceparent": "invalid", "baggage": "region=eu-west"},
 context=Context())
assert not trace.get_current_span(independent).get_span_context().is_valid
assert baggage.get_baggage("region", independent) == "eu-west"
untrusted = propagator.extract({"baggage": "tier=gold"}, context=Context())
assert baggage.get_baggage("tier", untrusted) == "gold"
print(json.dumps({"wire_fields": sorted(carrier),
 "wire_baggage": carrier["baggage"],
 "automatic_span_attributes": dict(spans["inherited"].attributes),
 "explicit_span_attributes": dict(spans["copied"].attributes),
 "baggage_survives_invalid_traceparent": True,
 "caller_supplied_tier_was_parsed": True}, indent=2))
provider.shutdown()

原始上下文包含区域、发布分组和一条完全虚构的内部备注。出站上下文只保留前两个字段，同时携带原父跨度。接收后区域应为 eu-west，发布值 canary/2 经过请求头编码后还原一致。断言还检查了筛选过程没有删除原上下文中的备注，也没有改变最初的空上下文。这说明清理出站载体与修改其他引用不是同一件事，后续代码必须使用正确的上下文对象。

两个子跨度进一步展示记录边界：inherited 收到行李上下文，但属性仍然为空；copied 只有显式设置的部署区域属性。另一个输入故意带有无效 traceparent，此时链路上下文无效，但独立编码的行李仍然可以解析。最后，调用方自称 tier=gold 的字符串也会被正常读取，过程中没有身份校验。链路断言只比较 trace_id，并未逐项检查所有链路上下文字段。把这套策略用于真实服务之前，还应检查客户端插桩、接收端提取、出站筛选和目标后台的属性映射，逐一确认实际行为与团队约定一致。

来源

Python assert statement，优化模式省略断言及其内部调用，已核验 2026-10-18。
OpenTelemetry baggage，行李上下文独立于遥测属性，且没有内置完整性保证，已核验 2026-10-15。
W3C Baggage，HTTP 表示、值编码与传播限制，已核验 2026-10-15。
W3C Trace Context，链路身份与应用行李上下文分别传播，已核验 2026-10-15。
OpenTelemetry Python 采样，显式采样器与环境默认值，已核验 2026-10-15。

BPF tracepoint 能窥探正在运行的内核

Mon, 06 Mar 2028 00:00:00 +0000

BPF 程序可以挂到正在运行的内核事件上，不必重新构建应用或重启业务负载，但仍需要用户态加载器负责加载和管理探针。采集会消耗资源，所以“实时”不等于不可见或没有成本。其他剖析工具也可以观察运行中的程序，选择 BPF 应取决于问题、已有插桩与获准的环境，而不是把所有传统工具都描述为必须暂停进程。

解释输出前，要定义事件、聚合键、观察时间和未覆盖的工作。系统调用次数、调度等待与设备延迟分布回答不同问题；没有选择相应事件与关联逻辑，就不能从一条计数命令推导文件延迟、TCP 重传或整台主机的全部行为。

不断流地探测

eBPF 程序可以在内核 map 中累计次数或直方图，同时让工作负载继续运行。聚合减少向用户态输出的数据，但每个被观察的事件仍可能执行探针逻辑。验证器按内核规则检查程序安全；接受加载不证明测量语义正确、开销可以忽略，也不是内核绝不可能发生故障的保证。不能给没有测量过的探针套用“个位数百分比”的通用成本。

从有边界的问题开始。统计系统调用进入次数需要入口事件；测量调用持续时间通常还要关联入口与出口状态。块设备延迟则需要另一套事件生命周期。bpftrace 等高级工具有助于表达这些测量，但代码短并不自动说明单位、过滤条件与关联方式正确；同一个直方图外观，也可能承载完全不同的观察对象。

tracepoint 是更稳定的名字

tracepoint 提供有名称的内核事件，通常比探测内部函数更少依赖实现细节，但不是稳定 ABI：名称与字段都可能随内核改变。kprobe 也可以按符号挂载，并非只能钉住硬编码地址；内部函数契约同样可能变化。长期保留的探针应注明实际验证过的版本，不能承诺补丁升级后原程序一定继续正确。

在目标内核上检查实际存在的事件及字段格式。能列出事件只证明可见性，不证明有权加载和挂载程序。找不到所需事件时，应记录覆盖范围限制，不能悄悄换成语义不同的事件，再把它的次数或耗时当作原问题的答案。选择入口、出口、调度或块层事件，都必须与要测量的边界一致。

读直方图，而不是开闸放水

聚合可以展示分布，避免逐条打印每个事件。延迟直方图可能提示快慢路径，但形状只是调查证据，不是诊断本身。没有测量对应区别，就不能从双峰断言某个路径造成异常，也不能凭外观认定慢请求恰好占百分之一。次数统计更不是延迟直方图，二者的坐标、单位与结论都应明确区分。

有意识地选择聚合键。按线程名称分组，可能合并同名的无关任务；改按标识或参数分组，则会改变基数和成本。尽早应用相关过滤，限定采集范围，报告时保留探针原文与负载条件。把结论与独立观察对照，再将应用问题归因于某个组件；不能因为某组计数最多，就直接把它称为耗时根因。

在获准的测试环境中比较挂载前后的业务延迟、CPU 与探针资源使用，并按具体工作负载确定可接受成本。不存在适用于所有探针的统一百分比门槛。延长打印间隔可能减少输出，却未必减少每个事件执行的工作；收紧事件或过滤条件时，也要重新说明因此失去的覆盖范围。

坏掉的样子

加载可能因权限、内核配置、事件不可用，或工具特定的 BTF、头文件要求而失败。保留实际错误，不能把所有失败都归结为环境，也不能删除检查来得到表面的成功。列出 tracepoint 不等于挂载成功；没有计数可能来自负载未发生、过滤不匹配或采集失败，不能据此宣布系统没有相关活动。

容器中的能力还取决于宿主内核及安全策略，不能为强行演示而削弱保护。热路径探针即使在内核内聚合，仍可能扰动工作负载，应在代表性条件下比较成本。改变过滤条件也会改变被观察总体，因此分布变化并不自动证明成本更低的测量更准确；应区分采集成本变化与样本范围变化。

入口尝试按当前线程名称合并。示意计数不是实测输出；限定范围的实验提案尚未运行。

快速验证

以下前台实验提案面向 bpftrace 0.24 与已经授权的主机，本轮没有执行。继续之前先确认版本、精确 tracepoint 与 /bin/cat；保留证据目录、标准错误和退出状态，不能为强行通过而提升权限。命令创建独立临时目录，只让指定子进程读取其中的固定普通文件，不把生产业务当成测试负载。

(
 work=$(mktemp -d) || exit 1
 printf 'Evidence directory: %s\n' "$work"
 cd "$work" || exit 1
 printf 'controlled input\n' > input || exit 1
 bpftrace --version || exit $?
 bpftrace -lv 'tracepoint:syscalls:sys_enter_openat' || exit $?
 if bpftrace -o counts.log -c '/bin/cat input' -e '
 tracepoint:syscalls:sys_enter_openat /pid == cpid/ {
 @opens[comm] = count();
 }' > workload.out 2> collector.err; then
 collector_status=0
 else
 collector_status=$?
 fi
 printf 'collector_status=%s\n' "$collector_status"
 cat collector.err
 if [ "$collector_status" -ne 0 ]; then exit "$collector_status"; fi
 cmp input workload.out || exit 1
 cat counts.log
)

核对过的 0.24 实现会在探针挂载后才通过 -c 启动这个有限子进程；pid == cpid 限定事件总体。观察随子进程生命周期结束，而不是睡眠十秒后猜测是否采集成功。子进程继承采集器权限，因此即使工作很小也需要事先授权。shell 明确保留前台采集器的退出状态，不把它冒充负载子进程的退出码；cmp 另外核对复制字节，也不证明子进程退出码。

预期结果是 cat 的入口计数，包含启动时打开文件和最终失败的尝试，而不是恰好一次成功打开。相同线程名称仍在选定总体内合并，不能据此推导延迟。空 map 或错误都不能解释成没有活动。挂载、结束清理与负载退出行为仍需获准运行后核验；本轮只审阅源契约，不能把静态检查升级为运行通过。

来源

bpftrace 项目，项目概览与追踪示例，已核验 2026-10-18。
eBPF 介绍，eBPF 官方文档，已核验 2026-09-05。
bpftrace 0.24 language，tracepoint 字段与次数、直方图聚合的区别，已核验 2026-10-18。
bpftrace 0.24 standard library，comm 表示当前线程名称，已核验 2026-10-18。
Linux BPF design Q&A，tracepoint 与 kprobe 挂载不是稳定 ABI，已核验 2026-10-18。
Linux BPF verifier，验证器检查不等于测量正确或低开销保证，已核验 2026-10-18。
GNU Bash manual，不指定子进程 ID 的 wait 不返回该子进程的失败状态，已核验 2026-10-18。
bpftrace 0.24 CLI，子进程生命周期、权限、cpid 过滤与独立追踪输出，已核验 2026-10-19。
bpftrace v0.24.0 runtime source，BPFtrace::run 先挂载探针，再启动非 USDT 子进程，已核验 2026-10-19。