SuperAPI AI 工具集

manual-instrumentation

通用与其它

查看项目

更新于 10-16 07:25

技能介绍

用途:该技能面向 OpenTelemetry 手动埋点的设计、实现与审查,适用于在代码中新增、修改或评审埋点。

主要能力与规则:只对有意义的运行时边界创建 span,不为辅助函数、循环体、纯校验、序列化胶水、getter 或纯计算埋点;写代码前先选信号,请求或操作流用 span,聚合性重复问题用 metrics,离散诊断事实用 logs 或 events,无价值则不埋。对 http、db、messaging、rpc 等已知边界类型,先查已发布的语义约定再定名称与属性,span 名直接由已发布命名规则推导,不添加自定义描述、协议标签、主机名、产品名或业务提示;无已发布键时使用稳定自定义命名空间并保持取值有界。取值优先方法、路由模板、状态码、操作名、目标名、区域、部署环境或客户层级,避免原始用户 ID、完整 URL、metrics 中的原始 SQL、自由文本和时间戳作为维度。失败记录在拥有最终失败结果的 span 上,重试成功不标记失败,已处理错误不视为终态失败。跨网络与异步边界保留 trace context,入站提取、出站注入,baggage 仅在有意且有界时使用。

使用方式:按规划、实现或审查模式执行;对每个埋点确定运行时边界、信号、语义约定组、关键属性与基数风险、传播需求,然后实现或审查,最后重新打开改动文件以证据核验。SDK 初始化、导出器、处理器、传播器与传输配置优先使用 sdk-setup 伴随技能;不可用时采用最小默认:traces 用 OTLP exporter 加 batch span processor,metrics 用 OTLP exporter 加 periodic exporting metric reader,logs 用 OTLP exporter 加 batching log record processor,传播器为 tracecontext,baggage;无 SDK 则配置,已有则复用,不额外增加信号。按需加载 references/boundaries.md、references/signal-selection.md、references/propagation.md。

限制:伴随技能不可用时不停止,也不仅凭记忆,应查官方 OpenTelemetry 发布源、文档、示例或源码,说明伴随技能不可用并引用回退来源,未核实项保持未解决而非猜测。使用项目语言最新兼容 SDK 或包,不兼容时用最新兼容版本并说明原因。核验清单以 [x] 完成、[~] 不适用并说明原因、[ ] 未解决标记,不得仅凭意图标记完成。具体版本号、价格与平台支持资料暂未提供。