Collect metrics using Micrometer

创建使用 Micrometer 指标库来收集运行时、扩展和应用程序指标并将其作为 Prometheus（开放指标）端点公开的应用程序。

Create an application that uses the Micrometer metrics library to collect runtime, extension and application metrics and expose them as a Prometheus (OpenMetrics) endpoint.

Prerequisites

Unresolved directive in telemetry-micrometer-tutorial.adoc - include::{includes}/prerequisites.adoc[]

Solution

建议您按照说明逐步创建应用程序，但如果您愿意，可以跳到解决方案。二者之一：

We recommend that you follow the instructions to create the application step by step, but you can skip right to the solution if you prefer. Either:

Clone the git repository: git clone {quickstarts-clone-url}, or
Download an {quickstarts-archive-url}[archive].

解决方案位于 micrometer-quickstart directory。

The solution is located in the micrometer-quickstart directory.

Create the Maven project

使用以下命令创建一个新项目：

Create a new project with the following command:

Unresolved directive in telemetry-micrometer-tutorial.adoc - include::{includes}/devtools/create-app.adoc[]

此命令会生成一个 Maven 项目，它导入 `micrometer-registry-prometheus`扩展作为依赖项。此扩展将加载核心 `micrometer`扩展以及支持 Prometheus 所需的其他库依赖项。

This command generates a Maven project, that imports the micrometer-registry-prometheus extension as a dependency. This extension will load the core micrometer extension as well as additional library dependencies required to support prometheus.

Create a REST endpoint

我们首先添加一个计算素数的简单端点。

Let’s first add a simple endpoint that calculates prime numbers.

Unresolved directive in telemetry-micrometer-tutorial.adoc - include::{generated-dir}/examples/telemetry-micrometer-tutorial-example-resource.java[]

在 dev 模式下启动应用程序：

Start your application in dev mode:

Unresolved directive in telemetry-micrometer-tutorial.adoc - include::{includes}/devtools/dev.adoc[]

Review automatically generated metrics

Micrometer 扩展自动计算 HTTP 服务器请求时间。

The Micrometer extension automatically times HTTP server requests.

我们使用 curl（或浏览器）访问我们的端点几次：

Let’s use curl (or a browser) to visit our endpoint a few times:

curl http://localhost:8080/example/prime/256
curl http://localhost:8080/example/prime/7919

Micrometer Prometheus MeterRegistry 扩展创建一个端点，我们可以使用它来观察收集的指标。让我们看看已经收集的指标：

The Micrometer Prometheus MeterRegistry extension creates an endpoint we can use to observe collected metrics. Let’s take a look at the metrics that have been collected:

curl http://localhost:8080/q/metrics

在输出中查找 http_server_requests_seconds_count、http_server_requests_seconds_sum`和 `http_server_requests_seconds_max。

Look for http_server_requests_seconds_count, http_server_requests_seconds_sum, and http_server_requests_seconds_max in the output.

添加维度标签以用于请求 URI、HTTP 方法（GET、POST 等）、状态代码（200、302、404 等）和一个更通用的结果字段。您应该找到类似这样的内容：

Dimensional labels are added for the request uri, the HTTP method (GET, POST, etc.), the status code (200, 302, 404, etc.), and a more general outcome field. You should find something like this:

# HELP http_server_requests_seconds
# TYPE http_server_requests_seconds summary
http_server_requests_seconds_count{method="GET",outcome="SUCCESS",status="200",uri="/example/prime/{number}"} 2.0
http_server_requests_seconds_sum{method="GET",outcome="SUCCESS",status="200",uri="/example/prime/{number}"} 0.017385896
# HELP http_server_requests_seconds_max
# TYPE http_server_requests_seconds_max gauge
http_server_requests_seconds_max{method="GET",outcome="SUCCESS",status="200",uri="/example/prime/{number}"} 0.017385896
#

指标会延迟出现，在访问端点之前，通常看不到任何数据。

Metrics appear lazily, you often won’t see any data for your endpoint until it is accessed.

Exported metrics format

默认情况下，度量使用 Prometheus 格式 application/openmetrics-text`导出，你可以通过将 `Accept 请求头指定为 text/plain (curl -H "Accept: text/plain" localhost:8080/q/metrics/) 来恢复为以前的形式。

Exported metrics format

By default, the metrics are exported using the Prometheus format application/openmetrics-text, you can revert to the former format by specifying the Accept request header to text/plain (curl -H "Accept: text/plain" localhost:8080/q/metrics/).

Inject the MeterRegistry

要注册指标，您需要一个 `MeterRegistry`的引用，该引用由 Micrometer 扩展配置并维护。

To register meters, you need a reference to the MeterRegistry that is configured and maintained by the Micrometer extension.

可以将 `MeterRegistry`注入到应用程序中，如下所示：

The MeterRegistry can be injected into your application as follows:

Unresolved directive in telemetry-micrometer-tutorial.adoc - include::{generated-dir}/examples/telemetry-micrometer-tutorial-example-resource.java[]

Add a Counter

计数器用于测量只会增加的值。

Counters are used to measure values that only increase.

让我们添加一个计数器来跟踪我们测试一个数字是否为素数的频率。我们将添加一个维度标签（也称为属性或标记），它将允许我们以不同的方式聚合此计数器值。

Let’s add a counter that tracks how often we test a number to see if it is prime. We’ll add a dimensional label (also called an attribute or a tag) that will allow us to aggregate this counter value in different ways.

Unresolved directive in telemetry-micrometer-tutorial.adoc - include::{generated-dir}/examples/telemetry-micrometer-tutorial-example-resource.java[]

1	Find or create a counter called `example.prime.number` that has a `type` label with the specified value.
2	Increment that counter.

Review collected metrics

如果您没有在 dev 模式下运行 Quarkus，请再次启动它：

If you did not leave Quarkus running in dev mode, start it again:

Unresolved directive in telemetry-micrometer-tutorial.adoc - include::{includes}/devtools/dev.adoc[]

尝试下面的序列，并查找纯文本输出中的 example_prime_number_total。

Try the following sequence and look for example_prime_number_total in the plain text output.

请注意，当 Micrometer 将 Prometheus 命名约定应用于 example.prime.number，即最初指定的计数器名称时，会添加 _total 后缀。

Note that the _total suffix is added when Micrometer applies Prometheus naming conventions to example.prime.number, the originally specified counter name.

curl http://localhost:8080/example/prime/-1
curl http://localhost:8080/example/prime/0
curl http://localhost:8080/example/prime/1
curl http://localhost:8080/example/prime/2
curl http://localhost:8080/example/prime/3
curl http://localhost:8080/example/prime/15
curl http://localhost:8080/q/metrics

请注意，每个 example_prime_number_total 和 type 值的唯一组合都会有一个计量值。

Notice that there is one measured value for each unique combination of example_prime_number_total and type value.

查看此计数器产生的维度数据，您可以计算：

Looking at the dimensional data produced by this counter, you can count:

how often a negative number was checked: type="not-natural"
how often the number one was checked: type="one"
how often an even number was checked: type="even"
how often a prime number was checked: type="prime"
how often a non-prime number was checked: type="not-prime"

您还可以通过汇总所有这些值来计算检查数字（一般）的次数。

You can also count how often a number was checked (generally) by aggregating all of these values together.

Add a Timer

计时器是用于测量持续时间的专业抽象。我们添加一个计时器来测量确定数字是否是质数需要多长时间。

Timers are a specialized abstraction for measuring duration. Let’s add a timer to measure how long it takes to determine if a number is prime.

Unresolved directive in telemetry-micrometer-tutorial.adoc - include::{generated-dir}/examples/telemetry-micrometer-tutorial-example-resource.java[]

1	Find or create a counter called `example.prime.number` that has a `type` label with the specified value.
2	Increment that counter.
3	Call a method that wraps the original `testPrimeNumber` method.
4	Create a `Timer.Sample` that tracks the start time
5	Call the method to be timed and store the boolean result
6	Find or create a `Timer` using the specified id and a `prime` label with the result value, and record the duration captured by the `Timer.Sample`.

Review collected metrics

如果您没有在 dev 模式下运行 Quarkus，请再次启动它：

If you did not leave Quarkus running in dev mode, start it again:

Unresolved directive in telemetry-micrometer-tutorial.adoc - include::{includes}/devtools/dev.adoc[]

Micrometer 会在为该计时器发出指标时应用 Prometheus 约定。具体来说，计量持续时间会被转换为秒，该单位会包含在指标名称中。

Micrometer will apply Prometheus conventions when emitting metrics for this timer. Specifically, measured durations are converted into seconds and this unit is included in the metric name.

尝试以下序列，并在纯文本输出中查找以下条目：

Try the following sequence and look for the following entries in the plain text output:

example_prime_number_test_seconds_count — how many times the method was called
example_prime_number_test_seconds_sum — the total duration of all method calls
example_prime_number_test_seconds_max — the maximum observed duration within a decaying interval. This value will return to 0 if the method is not invoked frequently.

curl http://localhost:8080/example/prime/256
curl http://localhost:8080/q/metrics
curl http://localhost:8080/example/prime/7919
curl http://localhost:8080/q/metrics

通过查看此计数器产生的维度数据，可以利用总和和数量计算确定一个数字是否为质数需要多长时间（平均时间）。通过使用维度标签，你可能会看出，对于质数和非质数，它们持续时间的显著差异。

Looking at the dimensional data produced by this counter, you can use the sum and the count to calculate how long (on average) it takes to determine if a number is prime. Using the dimensional label, you might be able to understand if there is a significant difference in duration for numbers that are prime when compared with numbers that are not.

Add a Gauge

测量仪会测量可以随时间推移而增大或减小的值，比如汽车上的车速表。测量仪的值不会累积，而是在收集时进行观察。使用测量仪来观察集合的大小，或函数返回的值。

Gauges measure a value that can increase or decrease over time, like the speedometer on a car. The value of a gauge is not accumulated, it is observed at collection time. Use a gauge to observe the size of a collection, or the value returned from a function.

Unresolved directive in telemetry-micrometer-tutorial.adoc - include::{generated-dir}/examples/telemetry-micrometer-tutorial-example-resource.java[]

1	Define list that will hold arbitrary numbers.
2	Register a gauge that will track the size of the list.
3	Create a REST endpoint to populate the list. Even numbers are added to the list, and odd numbers remove an element from the list.

Review collected metrics

如果您没有在 dev 模式下运行 Quarkus，请再次启动它：

If you did not leave Quarkus running in dev mode, start it again:

Unresolved directive in telemetry-micrometer-tutorial.adoc - include::{includes}/devtools/dev.adoc[]

然后尝试以下序列，并在纯文本输出中查找 example_list_size：

Then try the following sequence and look for example_list_size in the plain text output:

curl http://localhost:8080/example/gauge/1
curl http://localhost:8080/example/gauge/2
curl http://localhost:8080/example/gauge/4
curl http://localhost:8080/q/metrics
curl http://localhost:8080/example/gauge/6
curl http://localhost:8080/example/gauge/5
curl http://localhost:8080/example/gauge/7
curl http://localhost:8080/q/metrics

Summary

恭喜你！

Congratulations!

你已创建了一个项目，该项目利用 Micrometer 和 Prometheus Meter 注册扩展来收集指标。你已经观察了一些 Quarkus 自动捕获的指标，并且添加了一个 Counter 和 Timer，它们对应用程序来说是唯一的。你还向指标中添加了维度标签，并且已经观察到这些标签如何影响 Prometheus 端点发出的数据。

You have created a project that uses the Micrometer and Prometheus Meter Registry extensions to collect metrics. You’ve observed some of the metrics that Quarkus captures automatically, and have added a Counter and Timer that are unique to the application. You’ve also added dimensional labels to metrics, and have observed how those labels shape the data emitted by the prometheus endpoint.