无需改动任何工作流文件的 CI 流水线分布式追踪
内容提要
文章介绍使用 OpenTelemetry Collector 的 githubreceiver 组件，通过单一组织级 GitHub webhook 接收 workflow_run 和 workflow_job 事件，自动转换为 OTLP 追踪数据，无需各团队修改工作流文件。新仓库创建后即可观测，CI 追踪可与应用追踪在同一后端关联分析。需注意该组件仍为 alpha，应固定版本；配置需公开端点并限制 GitHub 来源 IP；容量应按活跃仓库而非仓库总数估算。
延伸解读
零侵入的代价：公开端点与安全边界
方案无需改动工作流文件，但 Collector 必须暴露公网端点供 GitHub 投递 webhook。文章提醒，不能只依赖共享密钥，应规划 IP 允许列表或 WAF 限制 GitHub 来源 IP；若密钥轮换麻烦，可考虑 GitHub App 方式。此外，组织级 webhook 需管理员权限，GitHub Enterprise Server 用户应先验证投递行为是否一致，避免上线中途才发现权限或兼容性问题。
容量估算：看活跃仓库，而非总数
文章强调，直接按组织仓库总数估算追踪量会严重高估，因为大量仓库处于休眠、归档或 fork 状态。正确方法是先统计一周内有真实工作流活动的仓库数，再乘以平均运行次数、平均步骤数和典型负载大小，推算每日数据量。多数组织中，CI 追踪量相对现有应用追踪量只是零头，用这个对比去沟通预算，比空口断言“量很小”更有说服力。
与 ARC 指标互补，而非替代
如果使用 Actions Runner Controller 自托管 runner，需明确本方案不替代 ARC 已有指标。ARC 关注 runner 队列深度、Pod 数量和自动扩缩容是否跟上；本方案关注工作流内部：某次运行为何慢、哪些任务不稳定、时间花在哪一步。队列深度和队列时间是从两个视角问同一个问题，文章建议两者都保留，而不是二选一。
alpha 组件的使用风险与配置陷阱
githubreceiver 仍是 contrib 中的 alpha 组件，配置接口可能变化。文章建议固定 Collector 版本，升级前查看 changelog，避免配置字段悄然改变。另一个易踩的坑是：即使只想要追踪，配置中也必须保留一个 scraper 条目（哪怕 dummy），否则校验失败。此外，span 和 trace ID 由运行 ID 和检查运行 ID 确定性哈希生成，便于步骤内自行发射遥测并挂到同一追踪上。
Q&A
如何在不修改任何工作流文件的情况下实现 CI 流水线的分布式追踪？
使用 OpenTelemetry Collector 的 githubreceiver 组件，在组织级别配置一个 GitHub webhook，接收 workflow_run 和 workflow_job 事件，并将其自动转换为 OTLP 追踪数据。这样无需各团队修改工作流文件，新仓库创建后即可自动被观测。
githubreceiver 组件将 GitHub 事件映射成什么样的追踪结构？
一个 workflow 对应一个外层 span，其中的每个 job 是子 span，job 内的每个 step 又是该 job 的子 span。span 和 trace ID 由 workflow 的 run ID 和每个 job 的 check run ID 确定性哈希生成，便于在步骤内自行发射遥测时直接关联到同一 trace。
部署 githubreceiver 前需要提前考虑哪些事项？
需要：1) 为 collector 提供公开可达的端点，并用 IP 允许列表或 WAF 限制为 GitHub webhook 来源 IP，而非仅依赖共享密钥；2) 可考虑使用 GitHub App 替代共享密钥管理；3) 确认组织管理员权限以设置组织级 webhook；4) 若使用 GitHub Enterprise Server，需先验证 webhook 投递行为是否一致；5) 该组件仍为 alpha，应固定 collector 版本并关注变更日志。
如何估算 CI 追踪的数据量以避免成本超支？
不要用仓库总数估算，因为大量休眠、复刻、归档仓库会虚增数量。应统计一周内有真实工作流活动的活跃仓库数，乘以每仓库平均运行次数得到工作流量，再乘以每工作流平均步骤数得到 span 量，最后乘以典型负载大小得到每日数据量。多数组织中 CI 追踪量相比应用追踪量只是零头。
githubreceiver 的配置中为什么必须包含 scrapers 块？
scrapers 块属于该 receiver 的另一项 GraphQL/REST 指标功能，与追踪无关，但配置验证要求至少有一个占位条目，否则即使只使用 webhook 追踪也会失败。这是一个容易浪费时间的配置细节。
这种 CI 追踪方案与 Actions Runner Controller 自带的指标有什么区别？
ARC 的指标关注 runner 集群层面：Pod 数量、自动扩缩容是否跟上、队列深度等。而本方案关注工作流层面：某次运行为何慢、哪些工作流不稳定、时间花在哪里。两者处于不同层次，队列深度和队列时间是从不同视角问的同一个问题，建议同时运行而非二选一。
为什么说这种零侵入的 CI 追踪方式比逐工作流埋点更好？
逐工作流埋点需要每个团队主动选择加入，新仓库在有人记得添加之前一直处于盲区，且 instrumentation 分散在大量工作流文件中，维护成本随组织规模增长。而组织级 webhook 方案只需配置一次，所有仓库（包括未来新建的）立即被覆盖，无需任何人记得开启。
