OpenTelemetry Metrics 是一个关于如何收集、聚合和发送指标到 OpenTelemetry APM 工具(如 Uptrace 或 Prometheus )的标准。在定义新标准的同时，OpenTelemetry 还致力于与现有的指标工具协议(如 Prometheus 和 Statsd)一起工作。此外，OpenTelemetry Collector 甚至支持更多的协议，如 AWS Metrics、InfluxDB、Chrony 等。

什么是指标?

指标是表示系统运行状况和性能的数值数据点，例如 CPU 利用率、网络流量和数据库连接。

您可以使用指标来度量、监视和比较性能，例如，您可以度量服务器响应时间、内存利用率、错误率等等。

Instruments

instrument 是一种特定类型的指标(例如，counter, gauge, histogram)，用于收集关于应用程序行为的特定方面的数据。

您通过创建具有以下功能的 instrument 来捕获测量结果:

• 唯一的名称，例如 http.server.duration。
• 一种 instrument 类型，例如 Histogram。
• 一个可选的指标单位，例如 milliseconds 或 bytes。
• 可选描述。

Timeseries(时间序列)

一个 instrument 可以生成多个时间序列。时间序列是一个具有唯一属性集的指标，例如，对于相同的指标名称，每个主机都有一个单独的时间序列。

Additive(可加) instruments

Additive 或 summable instruments 产生的时间序列，当加在一起时，产生另一个有意义和准确的时间序列。测量 non-decreasing 数的 Additive instruments 也称为 monotonic(单调的)。

例如，http.server.requests 是一个 additive 时间序列，因为您可以将来自不同主机的请求数相加，以获得请求总数。

但是，system.memory.utilization(百分比) 不是相加的，因为来自不同主机的内存利用率之和没有意义(90% + 90% = 180%)。

Synchronous(同步) instruments

Synchronous instruments 与它们正在测量的操作一起被调用。
例如，为了测量请求的数量，只要有新的请求，就可以调用 counter.Add(ctx, 1)。
同步测量可以具有关联的 trace context。

对于 synchronous instruments，additive 和 grouping instruments 之间的区别在于 additive instruments 产生 summable 时间序列，grouping instruments 产生 histogram。

Asynchronous(异步) instruments

Asynchronous instruments 定期调用回调函数来收集测量值。
例如，您可以使用观察器定期测量内存或 CPU 的使用情况。
Asynchronous 测量不能具有关联的 trace context。

在 UpDownCounterObserver (additive) 和 GaugeObserver (grouping)之间进行选择时，
对于 summable 时间序列，请选择 UpDownCounterObserver，否则，请选择 GaugeObserver。
例如，要测量 system.memory.usage (bytes)，应使用 UpDownCounterObserver。
但要测量 system.memory.utilization（百分比），您应该使用 GaugeObserver。

选择 instruments

1. 如果您需要直方图、热图或百分位数，请使用 Histogram。
2. 如果您想通过记录增量值来计数：
   • 如果该值是 monotonic 的，请使用 Counter。
   • 否则，使用 UpDownCounter。
3. 如果你想通过记录一个绝对值来测量某个东西：
   • 如果该值是 additive/summable 的：
     • 如果该值是 monotonic 的，请使用 CounterObserver。
     • 否则，请使用 UpDownCounterObserver。
   • 如果该值不 additive/summable，请使用 GaugeObserver。

Counter

synchronous monotonic

Counter 是一种同步 instrument，用于测量相加的非递减值，例如：

• processed requests
• errors
• received bytes
• disk reads

Counters 用于测量一个事件的发生次数或一个值随时间的累积。它们只能随着时间的推移而增加。

对于 Counter 时间序列，后端通常计算增量并显示速率值，例如，per_min(http.server.requests) 返回每分钟处理的请求数。

CounterObserver

asynchronous monotonic

CounterObserver 是 Counter instrument 的异步版本。

UpDownCounter

synchronous additive

UpDownCounter 是一种同步 instrument，用于测量可随时间增加或减少的附加值，例如：

• active requests
• open connections
• memory in use (megabytes)

对于加法非递减(non-decreasing)值，应使用 Counter 或 CounterObserver。

对于 UpDownCounter 时间序列，后端通常显示最后一个值，但不同的时间序列可以加在一起，
例如，go.sql.connections_open 返回打开的连接总数，
go.sql.connections_open{service.name = myservice} 返回一个服务的打开连接数。

UpDownCounterObserver

asynchronous additive

UpDownCounterOserver 是 UpDownCounter instrument 的异步版本。

Histogram

synchronous grouping

直方图是一种同步 instrument，它根据记录的值生成直方图，例如：

• request latency
• request size

直方图用于测量值随时间的分布。对于直方图时间序列，后端通常显示百分位数、热图和直方图。

GaugeObserver

asynchronous grouping

GaugeObserver 是一种异步 instrument，用于测量 sum 不能产生有意义或正确结果的非相加值，例如：

• error rate
• memory utilization
• cache hit rate

对于 GaugeObserver 时间序列，后端通常显示最后一个值，不允许将不同的时间序列相加。

Metrics 示例

邮件数量

要测量发送的电子邮件数量，您可以创建 Counter instrument，并在发送电子邮件时递增：

import "go.opentelemetry.io/otel/metric"

var emailCounter = meter.NewInt64Counter(
	"some.prefix.emails",
	metric.WithDescription("Number of sent emails"),
)

emailCounter.Add(ctx, 1)

稍后，您可以添加更多属性来收集详细的统计信息，例如：

• kind = welcome 和 kind = reset_password 可以测量不同的电子邮件。
• state = sent 和 state = bounced 以衡量退回的电子邮件。

操作延迟

要测量操作的延迟，您可以创建 Histogram instrument 并与操作同步更新：

import "go.opentelemetry.io/otel/metric"

var opHistogram = meter.NewInt64Histogram(
	"some.prefix.duration",
	metric.WithDescription("Duration of some operation"),
)

t1 := time.Now()
op(ctx)
dur := time.Since(t1)

opHistogram.Record(ctx, dur.Microseconds())

缓存命中率

要测量缓存命中率，可以创建一个 CounterObserver 并观察缓存统计信息：

import "go.opentelemetry.io/otel/metric"

var counter metric.Int64CounterObserver

// Arbitrary key/value labels.
hits := []attribute.KeyValue{attribute.String("type", "hits")}
misses := []attribute.KeyValue{attribute.String("type", "misses")}
errors := []attribute.KeyValue{attribute.String("type", "errors")}

batchObserver := meter.NewBatchObserver(
	func(ctx context.Context, result metric.BatchObserverResult) {
		stats := cache.Stats()

		result.Observe(hits, counter.Observation(int64(stats.Hits)))
		result.Observe(misses, counter.Observation(int64(stats.Misses)))
		result.Observe(errors, counter.Observation(int64(stats.Errors)))
	})

counter = batchObserver.NewInt64CounterObserver("some.prefix.cache_operations")

出错率

要直接测量错误率，您可以创建一个 GaugeObserver 并观察该值，而不必担心它是如何计算的：

import "go.opentelemetry.io/otel/metric"

_ = meter.NewFloat64GaugeObserver("some.prefix.error_rate",
	func(ctx context.Context, result metric.Float64ObserverResult) {
		result.Observe(rand.Float64())
	},
	metric.WithDescription("Error rate as reported by some other system"),
)