SuperAPI AI 工具集

semantic-conventions

通用与其它

查看项目

更新于 10-16 10:21

技能介绍

用途:在需要依据 OpenTelemetry 已发布语义约定进行命名、属性选择或合规检查时使用。若任务是手工埋点设计与评审,可搭配 manual-instrumentation 技能。

主要能力与工作流:以已发布语义约定为出发点而非依赖模型记忆;不把完整规范载入上下文,而是用内置查询脚本按需查询已发布的组或属性。先选择最接近的已发布组,再考虑自定义键:识别边界类型(如 http、db、messaging、rpc、network、gen-ai、mcp),先选一个主组,仅在能补充必要上下文时添加相关组,参考 references/semconv-selection.md。

用法:只查询所需的已发布指引。列出所有组:./scripts/query-otel-semantic-conventions.sh --groups;查看某个组:./scripts/query-otel-semantic-conventions.sh http;查看某类:./scripts/query-otel-semantic-conventions.sh http spans;查看具体属性或条目:./scripts/query-otel-semantic-conventions.sh http http.request.method。参见 references/otel-semantic-conventions.md。

应用规则:优先使用必需与推荐属性,再考虑可选属性;依据已发布的命名规则直接派生受语义约定约束的 Span 名称,不要为其前后附加协议标签、主机名、产品名、业务提示或其他自定义文本;若已发布命名规则未提供低基数目标,则使用该约定允许的更简单回退;若不存在已发布键,则使用稳定的自定义命名空间并保持取值有界。

返回结果:需附带精确来源上下文,包括脚本输出中的组名、已发布版本与来源 URL;如实现无法完全匹配已发布指引,需指出具体兼容性限制。