跳到主要内容

Micrometer OTLP

DeepSeek V3 中英对照 OpenTelemetry Protocol (OTLP) Micrometer OTLP

OpenTelemetry 是一个 CNCF 孵化项目，旨在为遥测数据提供标准。OpenTelemetry 协议（OTLP）是一个供应商中立的协议，您可以使用它将数据发送到支持该协议的各种后端。您可以阅读相应的文档，了解指标如何被摄取并可以在各个供应商的文档中进行可视化。

1. 安装 micrometer-registry-otlp​

建议使用 Micrometer（或您的框架，如果有）提供的 BOM，您可以在此处查看如何配置它 here。以下示例假设您正在使用 BOM。

1.1. Gradle​

在 配置 好 BOM 之后，添加以下依赖项：

implementation 'io.micrometer:micrometer-registry-otlp'
groovy
备注

这个依赖项不需要指定版本，因为它由 BOM 定义。

1.2. Maven​

在配置好 BOM 之后，添加以下依赖：

<dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-registry-otlp</artifactId>
</dependency>
xml
备注

由于该依赖项的版本由 BOM 定义，因此不需要指定版本。

2. 配置​

以下示例配置了一个 OTLP 注册表：

OtlpConfig otlpConfig = new OtlpConfig() {
            @Override
            public String get(final String key) {
                return null;
            }
};

MeterRegistry registry = new OtlpMeterRegistry(otlpConfig, Clock.SYSTEM);
java

OtlpConfig 是一个带有一组默认方法的接口。如果在 get(String k) 的实现中，你不返回 null，而是将其绑定到一个属性源（例如，一个简单的 Map 就可以工作），你可以通过属性覆盖默认配置。例如，Micrometer 的 Spring Boot 支持将带有前缀 management.otlp.metrics.export 的属性直接绑定到 OtlpConfig 上：

management:
  otlp:
    metrics:
      export:
        # Supported configs
        url: "https://otlp.example.com:4318/v1/metrics"
        batchSize: 15000
        aggregationTemporality: "cumulative"
        headers:
          header1: value1
        step: 30s
        resourceAttributes:
          key1: value1
yaml

  1. url - 数据上报的 URL。默认实现也支持环境变量 OTEL_EXPORTER_OTLP_METRICS_ENDPOINT 和 OTEL_EXPORTER_OTLP_ENDPOINT。如果未提供值，则默认为 [localhost:4318/v1/metrics](http://localhost:4318/v1/metrics)。

  2. batchSize - 包含在单个发送到后端的有效负载中的 Meter 数量。默认值为 10,000。

  3. aggregationTemporality - 聚合时间性决定了加性量如何随时间表达。默认实现支持环境变量 OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE。支持的值为 cumulative 或 delta。默认为 cumulative。

  4. headers - 与导出的指标一起发送的额外头部信息。这可以用于授权头部。默认情况下，头部从配置中加载。如果未设置，则可以从环境变量 OTEL_EXPORTER_OTLP_HEADERS 和 OTEL_EXPORTER_OTLP_METRICS_HEADERS 中获取。如果某个头部在两个环境变量中都设置了，则后者中的头部会覆盖前者。

  5. step - 指标发布的间隔时间。默认实现支持环境变量 OTEL_METRIC_EXPORT_INTERVAL。如果未提供值，则默认为 1 分钟。

  6. resourceAttributes - 资源属性用于所有发布的指标。默认情况下，Micrometer 添加以下资源属性：

键默认值
telemetry.sdk.nameio.micrometer
telemetry.sdk.languagejava
telemetry.sdk.version<micrometer-core-version> （例如：1.11.0）
service.nameunknown_service

如果此配置为空，资源属性将从 OTEL_RESOURCE_ATTRIBUTES 环境变量中加载。你可以通过设置 OTEL_SERVICE_NAME 环境变量来覆盖 service.name，并且这将优先于其他配置。

3. 支持的指标​

Metric points 定义了 OTLP 中支持的不同数据点。Micrometer 支持以 OTLP 格式导出以下数据点，

下表展示了 OTLP 数据点与 Micrometer 仪表之间的映射关系：

OTLP 数据点Micrometer 仪表类型
求和（Sums）计数器（Counter）、函数计数器（FunctionCounter）
仪表（Gauge）仪表（Gauge）、时间仪表（TimeGauge）、多仪表（MultiGauge）
直方图（Histogram）计时器（Timer）、分布摘要（DistributionSummary）、长任务计时器（LongTaskTimer）、函数计时器（FunctionTimer）（仅设置求和和计数）
指数直方图（Exponential Histogram*）计时器（Timer）、分布摘要（DistributionSummary）
摘要（Summary）计时器（Timer）、分布摘要（DistributionSummary）、长任务计时器（LongTaskTimer）

* - 直方图或指数直方图是根据 OtlpMeterRegistry 的配置决定的。更多信息请参见下面的部分。

注意:

  1. 直方图数据点上的 max 仅在增量聚合时间性中受支持。这是因为累积最小值和最大值所表示的值随着更多事件的记录而趋于稳定，并且在应用程序生命周期内记录时用处较小。

  2. 目前，Micrometer 仅将 Meter 类型的元数据导出到 OTLP。

4. 直方图和百分位数​

Micrometer 的 Timer 和 DistributionSummary 支持配置 客户端百分位数和百分位直方图。OTLP 规范将 Summary 数据点（客户端百分位数）视为遗留功能，并不建议在新应用中使用。此外，Summary 数据点也不能关联最小/最大值。由于这些原因，Micrometer 更倾向于将 Timer 和 DistributionSummary 导出为 Histogram 数据点。默认情况下，没有任何额外百分位数/直方图配置的 Timer/DistributionSummary 会被导出为 Histogram 数据点。然而，通过配置 Timer 仅生成客户端百分位数（使用 publishPercentiles），你可以将其更改为导出预计算百分位数的 Summary 数据点。当同时配置了 publishPercentiles 和（publishPercentileHistogram 或 serviceLevelObjectives）时，优先使用 Histogram 数据点，并且不会生成预计算的百分位数。下表描述了不同配置下使用哪种数据点：

配置OTLP 数据点
publishPercentiles摘要（Summary）
publishPercentileHistogram直方图/指数直方图 *
publishPercentiles 和 publishPercentileHistogram直方图/指数直方图 *
serviceLevelObjectives直方图
publishPercentiles 和 serviceLevelObjectives直方图

* 配置项 histogramFlavor 决定了 OTLP DataPoint 是直方图（Histogram）还是指数直方图（Exponential Histogram）。

OtlpMeterRegistry 在配置了 publishPercentileHistogram 时支持两种 Histogram 实现（1. 显式桶直方图（或简称为直方图），2. 指数直方图）。选择哪种实现通过在注册表中使用的 OtlpConfig 中的 histogramFlavor 设置来决定。当实现为指数直方图时，它还支持两个额外的属性。

  1. maxScale 用于限制指数直方图使用的最大 scale（默认值为 20）。

  2. maxBuckets 决定用于指数直方图的最大 buckets 数量（默认值为 160）。

由于指数直方图无法指定自定义 SLO，因此在添加了 serviceLevelObjectives 时，会使用显式桶直方图。

4.1. 使用 Spring Boot 进行配置​

如果你使用 Spring Boot，你可以使用 per-meter properties 来配置这种行为。

如果你想为名为 test.timer 的 Timer 生成一个直方图数据点，并使用 Micrometer 生成的默认桶，可以使用以下代码：

management.metrics.distribution.percentiles-histogram.test.timer=true
properties

对于具有自定义 SLO 的存储桶，请使用：

management.metrics.distribution.slo.test.timer=10.0,100.0,500.0,1000.0
properties

或者，如果你想为名为 test.timer 的计时器生成包含 90 和 99 百分位的 Summary 数据点，你可以使用：

management.metrics.distribution.percentiles.test.timer=0.9,0.99
properties