otel-semantic-conventions
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseOpenTelemetry Semantic Conventions
OpenTelemetry语义规范
Semantic conventions define standardized names, types, and semantics for telemetry attributes, span names, metric instruments, and log fields. They ensure that telemetry from different libraries, frameworks, and services describes the same concepts in the same way — enabling correlation, querying, and tooling across the entire stack.
The Attribute Registry is the single source of truth for all defined attributes.
语义规范为遥测属性、Span名称、度量工具和日志字段定义了标准化的名称、类型和语义。它们确保来自不同库、框架和服务的遥测数据以相同方式描述相同概念，从而实现整个技术栈的关联、查询和工具适配。
Attribute Registry是所有已定义属性的唯一可信来源。
Rules
规则
| Rule | Description |
|---|---|
| attributes | Attribute registry, selection, placement, common attributes by domain |
| versioning | Semconv versioning, stability, migration |
| dash0 | Dash0 derived attributes and feature dependencies |
| 规则 | 描述 |
|---|---|
| attributes | 属性注册表、选择、放置、按领域划分的通用属性 |
| versioning | 语义规范（Semconv）版本控制、稳定性、迁移 |
| dash0 | Dash0衍生属性及功能依赖 |
Official documentation
官方文档
Key principles
核心原则
- Registry first — Search the Attribute Registry before creating any custom attribute
- No custom attributes unless necessary — Custom names fragment querying and break tooling
- Low cardinality in names — Span names and metric attribute values must be bounded; variable data goes in attributes
- Right level, every time — Place attributes at the correct telemetry level (resource, scope, span, log, metric)
- Consistent placement — Once an attribute is at a level, keep it there across all services
- 优先使用注册表 — 创建任何自定义属性前，请先搜索Attribute Registry
- 非必要不使用自定义属性 — 自定义名称会分散查询逻辑并破坏工具兼容性
- 名称低基数 — Span名称和度量属性值必须是有限的；可变数据应放在属性中
- 始终选择正确层级 — 将属性放置在正确的遥测层级（resource、scope、span、log、metric）
- 放置保持一致 — 一旦属性确定了层级，所有服务中都要保持该层级不变
Quick reference
快速参考
| Use Case | Rule |
|---|---|
| Choosing or reviewing attributes | attributes |
| HTTP/DB/messaging/RPC attributes | attributes |
| Attribute placement (resource vs span) | attributes |
| Naming a span or choosing span kind | spans |
| Span status code mapping | spans |
| Semconv version migration | versioning |
| Dash0 derived attributes | dash0 |
| 使用场景 | 规则 |
|---|---|
| 选择或审核属性 | attributes |
| HTTP/数据库/消息队列/RPC属性 | attributes |
| 属性放置（resource vs span） | attributes |
| 命名Span或选择Span类型 | spans |
| Span状态码映射 | spans |
| 语义规范（Semconv）版本迁移 | versioning |
| Dash0衍生属性 | dash0 |