OpenTelemetry 命名约定
简介
OpenTelemetry(简称OTel)是云原生应用的可观测性标准工具集。良好的命名约定能确保你的遥测数据(指标、日志、追踪)具有一致的结构,便于团队协作和自动化分析。本文将介绍OTel的核心命名规则、实际案例和最佳实践。
为什么命名很重要?
混乱的命名会导致:
- 指标无法聚合
- 追踪难以关联
- 仪表盘数据不一致
核心命名规则
1. 通用原则
- 小写字母:所有名称使用小写(如
http.request.duration
) - 点分隔符:用点(
.
)表示层级关系 - 明确语义:避免缩写(用
database
而非db
)
2. 各信号类型规范
指标(Metrics)
<namespace>.<metric_name>.<unit>
namespace
:可选前缀,标识组件(如http
)unit
:标准化单位(完整列表见UCUM)
示例:
# 正确
http.server.request.duration.ms
custom.metrics.tasks.queue.size
# 避免
HTTP_Request_Time # 大写和下划线
req_time # 模糊
追踪(Traces)
- Span名称:使用
<操作名> <具体动作>
格式
// 正确
"GET /api/users"
"Database.QueryUsers"
// 避免
"query" // 太模糊
"do_something" // 非描述性
日志(Logs)
- 字段名:使用
snake_case
(如user_id
) - 保留字段前缀:
otel.
:OpenTelemetry专用(如otel.status_code
)app.
:应用自定义字段(如app.user_session
)