用途:为 OpenTelemetry 追踪实现提供规范指导,覆盖 span 设计、上下文传播、埋点方式、采样与 SDK 组件配置,目标是产出可聚合、可跨服务分析的追踪数据。
主要能力:
- Span 规范:按操作类别而非实例命名(低基数),正确设置 SpanKind(SERVER/CLIENT/PRODUCER/CONSUMER/INTERNAL),状态默认 Unset、失败设 Error,确保每个 span 都被 end。
- Span 数据:属性使用语义约定命名、低基数、创建时添加采样相关属性、不存 PII;事件用于有时间戳的注解;RecordException 需配合 setStatus(ERROR);链接用于跨 trace 关联。
- 上下文传播:采用 inject/extract 模式,默认 W3C TraceContext;异步代码显式传上下文;后台任务新建 trace 并链接回触发 span;baggage 不得放 PII 或凭据。
- 埋点:自动、手动或混合(推荐生产用混合);tracer 以库/模块命名并带版本;库只依赖 API 不依赖 SDK。
- 采样:头采样(AlwaysOn、AlwaysOff、TraceIdRatioBased、ParentBased)与尾采样(需 Collector,按 trace ID 缓冲);建议先不采样,错误始终保留,过滤健康检查。
- SDK 组件:TracerProvider 启动时初始化一次、退出时 shutdown;生产用 BatchSpanProcessor;Resource 配置 service.name。
使用方式:技能内含 spans、span-data、context-propagation、instrumentation、sampling、semantic-conventions、sdk-components 等参考文档,路径形如 ${CLAUDE_SKILL_DIR}/references/spans.md,按需查阅。
适用场景:编写或审查追踪代码、设计 span 粒度与属性、配置采样与 SDK、排查追踪缺失或上下文断裂问题。
限制:具体语言 SDK API 差异由对应语言技能处理;本技能只约束追踪实现选择。资料未提供具体安装命令、收费与平台信息。