Skill v0.1.0
currentAutomated scan100/100name: "distributed-tracing" display_name: "分布式追踪" display_name_en: "Distributed Tracing" description: "Use when instrumenting or diagnosing distributed requests, service dependencies, latency, retries, failures, or trace-to-log correlation." description_zh: "用于埋点或诊断跨服务请求、依赖关系、延迟、重试、故障和 trace 与日志关联。" description_en: "Implement privacy-safe OpenTelemetry tracing with context propagation, sampling, semantic spans, trace-log correlation, bottleneck analysis, and bounded overhead." category: "observability" version: "0.1.0" author: "wshobson/agents; adapted for WorkBuddy by SandBase AI" license: "MIT" compatibility: "WorkBuddy with authorized telemetry access, an OpenTelemetry-compatible collector/backend, and a non-production validation target; instrumentation changes and telemetry retention require separate authorization"
Distributed Tracing
用 trace 重建一次请求跨服务、队列、数据库和外部 API 的路径,回答“哪里慢、哪里失败、哪次变更影响了它”。追踪是抽样的诊断证据,不是完整审计日志;必须同时管理上下文、隐私、采样、保留、成本和证据局限。
使用边界
- 开始前确认服务拓扑、协议、OpenTelemetry/SDK 版本、collector、采样策略、保留周期、数据区域和访问权限。
- 默认只读检查 instrumentation、trace、span、日志、指标和部署变更;先在本地/预发布或脱敏流量验证。
- 不擅自修改生产采样率、collector 路由、保留策略、网络策略或重启服务;这些变更需要明确授权与回滚计划。
- span attributes、events、baggage 和日志不得写入 token、密码、完整请求/响应、原始 query、邮件、手机号或稳定的用户标识。需要关联时使用短期、不可逆、受控的 correlation ID。
追踪契约
统一服务名、环境、版本、区域和 operation 名称;span 名称描述动作而不是动态值,例如 GET /orders/{id},不要把订单号放入名称。每个跨进程边界传播 W3C Trace Context;队列要区分 producer/consumer,异步任务保留 parent/links 的语义。
为关键 span 规定必需字段、允许枚举、敏感字段清单、错误语义、超时和采样规则。HTTP、数据库、消息和 RPC 优先使用 OpenTelemetry 语义约定,避免同一事实在不同服务使用不同名称。
from opentelemetry import tracetracer = trace.get_tracer("orders-service")def process_order(order_ref: str):# Keep only a non-sensitive operation reference; never attach raw payloads.with tracer.start_as_current_span("process order") as span:span.set_attribute("app.operation", "order.process")try:result = reserve_inventory(order_ref)span.add_event("inventory.reserved", {"item_count": result.count})return resultexcept TimeoutError as exc:span.record_exception(exc)span.set_status(Status(StatusCode.ERROR, "dependency timeout"))raise
采样与成本
头部采样适合控制基础成本,尾部采样可保留错误、慢请求和特定业务路径,但要评估 collector 内存、决策延迟和丢失风险。生产采样率应由流量、SLO、诊断目标、存储成本和隐私要求共同决定;“1–10%”只是起点,不能当作普遍正确值。
使用 batch span processor、队列上限、export timeout 和 backpressure;telemetry 发送失败不能阻断业务请求。测量 instrumentation 的 CPU、内存、网络和 p95/p99 延迟开销,设定可告警阈值,并为高基数 attributes 设置白名单。
传播、日志与指标关联
检查 HTTP/RPC headers、消息 metadata、线程/异步 context、重试和跨进程边界。不要把来自请求的 baggage 当作可信授权信息,也不要无条件把 baggage 复制到下游;只传播经过验证、最小化和有保留策略的字段。
日志使用 trace ID/span ID 做关联,但日志内容仍需独立脱敏和访问控制。用 metrics 发现总体 SLO 变化,用 traces 解释单次路径,用 logs 补充离散错误;不要用单条 trace 推断全体用户或全部请求的可靠性。
故障与性能诊断
先确认 trace 完整性:采样、时钟偏差、collector 丢弃、上下文断裂、重试和 fan-out 是否造成误读。沿 critical path 对比同类成功/失败和变更前后 trace,区分应用耗时、队列等待、连接池、DNS/TLS、数据库、下游限流和重试放大。
没有 trace 时按层排查 exporter endpoint、TLS/权限、collector pipeline、采样和 SDK 配置;不要通过提高采样率无限期解决丢失。高开销时先减少 payload 和高基数属性、启用批处理与限流,再验证采样变化的诊断损失。
验证与交付
在隔离环境生成带固定 correlation 的成功、超时、异常、重试、异步和取消流量,验证每个边界的 parent/child/link、span 状态、错误事件、日志关联和敏感字段清理。对 trace 缺失、部分采样、collector 不可用和服务重启测试降级行为。
交付报告记录代码/SDK/collector 版本、拓扑、采样与保留策略、完整性缺口、基线与开销、查询时间范围、代表性 trace、日志/指标证据、隐私审查、成本和回滚步骤;把 observed、derived、unknown 分开。
质量门禁
- [ ] 服务、协议、operation、版本和环境命名符合统一追踪契约。
- [ ] HTTP/RPC/队列/异步边界传播 context,重试、取消、fan-out 和跨线程语义已验证。
- [ ] 采样、尾部决策、批处理、队列上限、超时、丢弃和成本有明确依据。
- [ ] span/log/metric 关联可用,且无 secret、原始 payload、用户标识或高基数泄露。
- [ ] 成功、失败、慢请求、重试、collector 故障和部分采样均有隔离测试。
- [ ] 生产 instrumentation、采样、路由、保留和网络变更均有授权和回滚方案。