mcpField
O
otel-semantic-conventions

otel-semantic-conventions

github.com/dash0hq云与 DevOps98705 次安装1 周前更新
代码仓库

关于 otel-semantic-conventions

otel-semantic-conventions 是用于依据 OpenTelemetry 语义约定选择、放置和验证遥测属性及指标的技能，面向编写或审查遥测数据的开发者。它强调以属性注册表为准，并提供版本管理和 Dash0 派生属性指引。

主要功能

  1. 01按注册表选择标准属性
  2. 02区分资源与 Span 属性
  3. 03检查属性稳定性与基数
  4. 04指导语义约定版本迁移
  5. 05说明 Dash0 派生属性

适用场景

  1. 01审查 HTTP、数据库或 RPC 属性
  2. 02判断属性应放在资源还是 Span
  3. 03避免指标属性出现高基数值
  4. 04迁移语义约定版本

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/dash0hq/agent-skills --skill otel-semantic-conventions

安装后在 Claude Code 中输入/otel-semantic-conventions确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

rules/
attributes.md
dash0.md
versioning.md

详细介绍

OpenTelemetry 语义约定

此技能用于根据 OpenTelemetry 语义约定规范，正确选择、放置和验证遥测属性及指标仪器。 有关 span 命名、span 类型和 span 状态码，请参阅 otel-instrumentation 技能。

属性注册表 是所有已定义属性的唯一事实来源。

规则

规则描述使用场景
attributes属性注册表、选择、放置、各领域常用属性选择或审查属性；HTTP/DB/消息传递/RPC 属性；属性放置（资源与 span）
versioningSemconv 版本管理、稳定性、迁移Semconv 版本迁移
dash0Dash0 派生属性及功能依赖Dash0 派生属性

官方文档

如何选择合适的属性

  1. 先搜索注册表 — 在属性注册表中查找相关概念。如果存在标准名称，就使用该名称（例如，优先使用 http.request.method，而不是自定义的 custom.http.verb）。自定义名称会导致查询碎片化并破坏工具的正常工作——只有在注册表中没有涵盖该概念的条目时，才创建自定义属性。
  2. 检查稳定性 — 优先选择 stable 属性；留意可能会变更的 experimental 属性。请参阅 versioning。
  3. 放置在正确的层级 — 资源属性描述生成遥测数据的实体；span/日志属性描述单个操作。不要在多个层级重复设置。一旦确定某个属性所属的层级，就要在所有服务中保持一致。
  4. 验证基数 — 指标属性的值必须是低基数（有限集合）。可变数据（用户 ID、带参数的请求路径）应放在 span 属性中，而不是指标属性中。
  5. 仅在不得已时使用自定义属性 — 只有在注册表中没有涵盖该概念的条目时，才创建自定义属性。记录这一决定，并遵循 org.namespace.attribute_name 命名模式。
示例：正确与错误的属性选择
# Correct — uses registry attribute for HTTP method
span.set_attribute("http.request.method", "GET")

# Incorrect — invents a custom attribute for a concept already in the registry
span.set_attribute("custom.http.verb", "GET")
示例：资源属性与 span 属性的放置
# Correct — service identity is a resource attribute
resource = Resource({"service.name": "checkout-service", "service.version": "2.1.0"})

# Correct — operation-specific data is a span attribute
span.set_attribute("http.request.method", "POST")
span.set_attribute("http.response.status_code", 201)

# Incorrect — placing a resource-level attribute on every span
span.set_attribute("service.name", "checkout-service")  # belongs on the resource
示例：指标属性中的基数违规
# Correct — metric attribute uses a bounded, low-cardinality value
histogram.record(duration_ms, {"http.request.method": "GET", "http.response.status_code": 200})

# Incorrect — unbounded values as metric attributes explode storage and query cost
histogram.record(duration_ms, {"user.id": "u-839201", "url.path": "/orders/839201"})
# Fix: move high-cardinality values to span attributes instead
span.set_attribute("user.id", "u-839201")
span.set_attribute("url.path", "/orders/839201")

评论

支持 Markdown