跳到主要内容

OpenTelemetry 指标名称约定

介绍​

在OpenTelemetry中，**指标（Metrics）**用于量化系统的行为（如请求延迟、错误率等）。良好的命名约定能确保指标清晰、一致且易于理解。本文将介绍OpenTelemetry推荐的指标命名规则，并通过实际案例展示如何应用这些规则。

指标名称的结构​

OpenTelemetry指标名称由以下部分组成：

  1. 命名空间（可选）：标识指标所属的领域（如 http.）。
  2. 基本名称：描述测量的内容（如 request.duration）。
  3. 单位（可选）：明确指标的单位（如 seconds）。

格式示例：
<namespace>.<basename>.<unit>
或
<basename>.<unit>

提示

单位应使用标准缩写（如 ms 表示毫秒，bytes 表示字节），避免自定义单位。

命名规则​

1. 使用小写字母和点分隔符​

指标名称应全部小写，并用点（.）分隔层级。
正确示例：
http.request.duration
错误示例：
HTTP_Request_Duration

2. 避免特殊字符​

仅允许使用字母、数字和点（.），避免连字符（-）或下划线（_）。

3. 语义明确​

名称应直接描述测量内容，避免模糊术语。
良好示例：
db.query.count
模糊示例：
db.operation

4. 包含单位（可选）​

如果单位对理解指标至关重要，可以附加到名称中。
示例：
network.transmit.bytes

实际案例​

案例1：HTTP请求监控​

假设需要监控Web服务的请求延迟和次数：

  • 请求延迟：http.server.request.duration.seconds
  • 请求计数：http.server.request.count
python
from opentelemetry import metrics

meter = metrics.get_meter("http.meter")

# 定义指标
request_duration = meter.create_histogram(
    name="http.server.request.duration.seconds",
    description="Duration of HTTP requests in seconds",
)

request_count = meter.create_counter(
    name="http.server.request.count",
    description="Total number of HTTP requests",
)

案例2：数据库查询​

监控数据库查询的耗时和错误：

  • 查询耗时：db.query.duration.milliseconds
  • 查询错误：db.query.error.count
go
import "go.opentelemetry.io/otel/metric"

meter := metric.NewMeter("db.meter")

queryDuration, _ := meter.Float64Histogram(
    "db.query.duration.milliseconds",
    metric.WithDescription("Database query duration in milliseconds"),
)

queryErrors, _ := meter.Int64Counter(
    "db.query.error.count",
    metric.WithDescription("Total database query errors"),
)

总结​

遵循OpenTelemetry的指标命名约定可以：

  1. 提高指标的可读性和一致性。
  2. 避免团队间的命名冲突。
  3. 简化跨系统的指标集成和分析。
警告

避免在名称中包含动态变量（如用户ID），这类信息应通过**属性（Attributes）**传递。

扩展练习​

  1. 为你的应用程序设计以下指标的命名：

    • CPU使用率
    • 内存占用
    • 缓存命中率

  2. 比较OpenTelemetry与Prometheus的命名约定差异（如 _ vs . 分隔符）。

附加资源​