选择指南版本

Using OpenTelemetry Metrics

This guide explains how your Quarkus application can utilize OpenTelemetry (OTel) to provide metrics for interactive web applications.

这项技术被认为是preview。

在 preview(预览) 中，不保证向后兼容和在生态系统中的存在。具体的改进可能需要改变配置或API，并且正在计划变得稳定。欢迎在我们的邮件列表中提供反馈，或在我们的 GitHub问题列表中提出问题。

For a full list of possible statuses, check our FAQ entry.

OpenTelemetry Metrics is considered tech preview and is disabled by default.
The OpenTelemetry Guide is available with signal independent information about the OpenTelemetry extension.
If you search more information about OpenTelemetry Tracing, please refer to the OpenTelemetry Tracing Guide.

先决条件

完成这个指南，你需要:

大概15分钟
编辑器
JDK 17+ installed with JAVA_HOME configured appropriately
Apache Maven 3.9.9
Docker and Docker Compose or Podman, and Docker Compose
如果你愿意的话，还可以选择使用Quarkus CLI
如果你想构建原生可执行程序，可以选择安装Mandrel或者GraalVM，并正确配置(或者使用Docker在容器中进行构建)

应用结构

在本指南中，我们创建了一个简单的REST应用程序来演示分布式跟踪服务。

解决方案

我们建议您按照下面几节的说明，一步一步地创建应用程序。不过，您可以直接跳到已完成的例子。

克隆 Git 仓库: git clone https://github.com/quarkusio/quarkus-quickstarts.git ，或下载一个存档。

The solution is located in the opentelemetry-quickstart directory.

创建Maven项目

首先，我们需要一个全新的项目。用以下命令创建一个新项目：

CLI

quarkus create app org.acme:opentelemetry-quickstart \
    --extension='rest,quarkus-opentelemetry' \
    --no-code
cd opentelemetry-quickstart

创建Grade项目，请添加 --gradle 或者 --gradle-kotlin-dsl 参数。

For more information about how to install and use the Quarkus CLI, see the Quarkus CLI guide.

Maven

mvn io.quarkus.platform:quarkus-maven-plugin:3.16.3:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=opentelemetry-quickstart \
    -Dextensions='rest,quarkus-opentelemetry' \
    -DnoCode
cd opentelemetry-quickstart

创建Grade项目，请添加 -DbuildTool=gradle 或者 -DbuildTool=gradle-kotlin-dsl 参数。

For Windows users:

If using cmd, (don’t use backward slash \ and put everything on the same line)
If using Powershell, wrap -D parameters in double quotes e.g. "-DprojectArtifactId=opentelemetry-quickstart"

This command generates the Maven project and imports the quarkus-opentelemetry extension, which includes the default OpenTelemetry support, and a gRPC span exporter for OTLP.

If you already have your Quarkus project configured, you can add the quarkus-opentelemetry extension to your project by running the following command in your project base directory:

CLI

quarkus extension add opentelemetry

Maven

./mvnw quarkus:add-extension -Dextensions='opentelemetry'

Gradle

./gradlew addExtension --extensions='opentelemetry'

这将在您的构建文件中添加以下内容：

pom.xml

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-opentelemetry</artifactId>
</dependency>

build.gradle

implementation("io.quarkus:quarkus-opentelemetry")

Examine the Jakarta REST resource

Create a src/main/java/org/acme/opentelemetry/MetricResource.java file with the following content:

package org.acme;

import io.opentelemetry.api.metrics.LongCounter;
import io.opentelemetry.api.metrics.Meter;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import org.jboss.logging.Logger;

@Path("/hello-metrics")
public class MetricResource {

    private static final Logger LOG = Logger.getLogger(MetricResource.class);

    private final LongCounter counter;

    public MetricResource(Meter meter) { (1)
        counter = meter.counterBuilder("hello-metrics") (2)
                .setDescription("hello-metrics")
                .setUnit("invocations")
                .build();
    }

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {
        counter.add(1); (3)
        LOG.info("hello-metrics");
        return "hello-metrics";
    }
}

Quarkus is not currently producing metrics out of the box. Here we are creating a counter for the number of invocations of the hello() method.

1	Constructor injection of the `Meter` instance.
2	Create a `LongCounter` named `hello-metrics` with a description and unit.
3	Increment the counter by one for each invocation of the `hello()` method.

创建配置

The only mandatory configuration for OpenTelemetry Metrics is the one enabling it:

quarkus.otel.metrics.enabled=true

To change any of the default property values, here is an example on how to configure the default OTLP gRPC Exporter within the application, using the src/main/resources/application.properties file:

quarkus.application.name=myservice (1)
quarkus.otel.metrics.enabled=true (2)
quarkus.otel.exporter.otlp.metrics.endpoint=http://localhost:4317 (3)
quarkus.otel.exporter.otlp.metrics.headers=authorization=Bearer my_secret (4)

1	All metrics created from the application will include an OpenTelemetry `Resource` indicating the metrics was created by the `myservice` application. If not set, it will default to the artifact id.
2	Enable the OpenTelemetry metrics. Must be set at build time.
3	gRPC endpoint to send the metrics. If not set, it will default to `http://localhost:4317`.
4	Optional gRPC headers commonly used for authentication.

To configure the connection using the same properties for all signals, please check the base configuration section of the OpenTelemetry guide.

To disable particular parts of OpenTelemetry, you can set the properties listed in this section of the OpenTelemetry guide.

运行应用程序

First we need to start a system to visualise the OpenTelemetry data.

See the data

Grafana-OTel-LGTM Dev Service

You can use the Grafana-OTel-LGTM devservice.

This Dev service includes a Grafana for visualizing data, Loki to store logs, Tempo to store traces and Prometheus to store metrics. Also provides and OTel collector to receive the data.

Logging exporter

You can output all metrics to the console by setting the exporter to logging in the application.properties file:

quarkus.otel.metrics.exporter=logging (1)
quarkus.otel.metric.export.interval=10000ms (2)

1	Set the exporter to `logging`. Normally you don’t need to set this. The default is `cdi`.
2	Set the interval to export the metrics. The default is `1m`, which is too long for debugging.

Also add this dependency to your project:

<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-exporter-logging</artifactId>
</dependency>

Start the application

现在我们准备运行我们的应用程序。如果使用 application.properties 来配置tracer：

CLI

quarkus dev

Maven

./mvnw quarkus:dev

Gradle

./gradlew --console=plain quarkusDev

或者如果通过JVM参数配置OTLP gRPC节点：

CLI

quarkus dev -Djvm.args="-Dquarkus.otel.exporter.otlp.endpoint=http://localhost:4317"

Maven

./mvnw quarkus:dev -Djvm.args="-Dquarkus.otel.exporter.otlp.endpoint=http://localhost:4317"

Gradle

./gradlew --console=plain quarkusDev -Djvm.args="-Dquarkus.otel.exporter.otlp.endpoint=http://localhost:4317"

With the OpenTelemetry Collector, the Jaeger system and the application running, you can make a request to the provided endpoint:

$ curl http://localhost:8080/hello-metrics
hello-metrics

When using the logger exporter, metrics will be printed to the console. This is a pretty printed example:

{
  "metric": "ImmutableMetricData",
  "resource": {
    "Resource": {
      "schemaUrl": null,
      "attributes": { (1)
        "host.name": "myhost",
        "service.name": "myservice ",
        "service.version": "1.0.0-SNAPSHOT",
        "telemetry.sdk.language": "java",
        "telemetry.sdk.name": "opentelemetry",
        "telemetry.sdk.version": "1.32.0",
        "webengine.name": "Quarkus",
        "webengine.version": "999-SNAPSHOT"
      }
    },
    "instrumentationScopeInfo": {
      "InstrumentationScopeInfo": { (2)
        "name": "io.quarkus.opentelemetry",
        "version": null,
        "schemaUrl": null,
        "attributes": {}
      }
    },
    "name": "hello-metrics", (3)
    "description": "hello-metrics",
    "unit": "invocations",
    "type": "LONG_SUM",
    "data": {
      "ImmutableSumData": {
        "points": [
          {
            "ImmutableLongPointData": {
              "startEpochNanos": 1720622136612378000,
              "epochNanos": 1720622246618331000,
              "attributes": {},
              "value": 3, (4)
              "exemplars": [ (5)
                {
                  "ImmutableLongExemplarData": {
                    "filteredAttributes": {},
                    "epochNanos": 1720622239362357000,
                    "spanContext": {
                      "ImmutableSpanContext": {
                        "traceId": "d91951e50b0641552a76889c5356467c",
                        "spanId": "168af8b7102d0556",
                        "traceFlags": "01",
                        "traceState": "ArrayBasedTraceState",
                        "entries": [],
                        "remote": false,
                        "valid": true
                      },
                      "value": 1
                    }
                  }
                }
              ]
            }
          }
        ],
        "monotonic": true,
        "aggregationTemporality": "CUMULATIVE"
      }
    }
  }
}

1	Resource attributes common to all telemetry data.
2	Instrumentation scope is allways `io.quarkus.opentelemetry`
3	The name, description and unit of the metric you defined in the constructor of the `MetricResource` class.
4	The value of the metric. 3 invocations were made until now.
5	Exemplars additional tracing information about the metric. In this case, the traceId and spanId of one os the request that triggered the metric, since it was last sent.

Hit CTRL+C or type q to stop the application.

Create your own metrics

OpenTelemetry Metrics vs Micrometer Metrics

Metrics are single numerical measurements, often have additional data captured with them. This ancillary data is used to group or aggregate metrics for analysis.

Pretty much like in the Quarkus Micrometer extension, you can create your own metrics using the OpenTelemetry API and the concepts are analogous.

The OpenTelemetry API provides a Meter interface to create metrics instead of a Registry. The Meter interface is the entry point for creating metrics. It provides methods to create counters, gauges, and histograms.

Attributes can be added to metrics to add dimensions, pretty much like tags in Micrometer.

Obtain a reference to the Meter

Use one of the following methods to obtain a reference to a Meter:

Use CDI Constructor injection

@Path("/hello-metrics")
public class MetricResource {

    private final Meter meter;

    public MetricResource(Meter meter) {
        this.meter = meter;
    }
}

Pretty much like in the example above.

Member variable using the `@Inject` annotation

@Inject
Meter meter;

计数器（Counters）

Counters can be used to measure non-negative, increasing values.

LongCounter counter = meter.counterBuilder("hello-metrics") (1)
        .setDescription("hello-metrics")                    // optional
        .setUnit("invocations")                             // optional
        .build();

counter.add(1, (2)
        Attributes.of(AttributeKey.stringKey("attribute.name"), "attribute value")); // optional (3)

1	Create a `LongCounter` named `hello-metrics` with a description and unit.
2	Increment the counter by one.
3	Add an attribute to the counter. This will create a dimension called `attribute.name` with value `attribute value`.

Each unique combination of metric name and dimension produces a unique time series. Using an unbounded set of dimensional data (many different values like a userId) can lead to a "cardinality explosion", an exponential increase in the creation of new time series. Avoid!

OpenTelemetry provides many other types of Counters: LongUpDownCounter, DoubleCounter, DoubleUpDownCounter and also Observable, async counters like ObservableLongCounter, ObservableDoubleCounter, ObservableLongUpDownCounter and ObservableDoubleUpDownCounter.

For more details please refer to the OpenTelemetry Java documentation about Counters.

Gauges

Observable Gauges should be used to measure non-additive values. A value that can increase or decrease over time, like the speedometer on a car. Gauges can be useful when monitoring the statistics for a cache or collection.

With this metric you provide a function to be periodically probed by a callback. The value returned by the function is the value of the gauge.

The default gauge records Double values, but if you want to record Long values, you can use

meter.gaugeBuilder("jvm.memory.total")                      (1)
        .setDescription("Reports JVM memory usage.")
        .setUnit("byte")
        .ofLongs()                                          (2)
        .buildWithCallback(                                 (3)
                result -> result.record(
                        Runtime.getRuntime().totalMemory(), (4)
                        Attributes.empty()));               // optional (5)

1	Create a `Gauge` named `jvm.memory.total` with a description and unit.
2	If you want to record `Long` values you need this builder method because the default gauge records `Double` values.
3	Build the gauge with a callback. An imperative builder is also available.
4	Register the function to call to get the value of the gauge.
5	No added attributes, this time.

Histograms

Histograms are synchronous instruments used to measure a distribution of values over time. It is intended for statistics such as histograms, summaries, and percentile. The request duration and response payload size are good uses for a histogram.

On this section we have a new class, the HistogramResource that will create a LongHistogram.

package org.acme;

import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.common.Attributes;
import io.opentelemetry.api.metrics.LongHistogram;
import io.opentelemetry.api.metrics.Meter;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;
import org.jboss.logging.Logger;

import java.util.Arrays;

@Path("/roll-dice")
public class HistogramResource {

    private static final Logger LOG = Logger.getLogger(HistogramResource.class);

    private final LongHistogram rolls;

    public HistogramResource(Meter meter) {
        rolls = meter.histogramBuilder("hello.roll.dice")  (1)
                .ofLongs()                                 (2)
                .setDescription("A distribution of the value of the rolls.")
                .setExplicitBucketBoundariesAdvice(Arrays.asList(1L, 2L, 3L, 4L, 5L, 6L, 7L)) (3)
                .setUnit("points")
                .build();
    }

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String helloGauge() {
        var roll = roll();
        rolls.record(roll,                                 (4)
                Attributes.of(AttributeKey.stringKey("attribute.name"), "value"));            (5)
        LOG.info("roll-dice: " + roll);
        return "" + roll;
    }

    public long roll() {
        return (long) (Math.random() * 6) + 1;
    }
}

1	Create a `LongHistogram` named `hello.roll.dice` with a description and unit.
2	If you want to record `Long` values you need this builder method because the default histogram records `Double` values.
3	Set the explicit bucket boundaries for the histogram. The boundaries are inclusive.
4	Record the value of the roll.
5	Add an attribute to the histogram. This will create a dimension called `attribute.name` with value `value`.

Beware of cardinality explosion.

We can invoke the endpoint with a curl command.

$ curl http://localhost:8080/roll-dice
2

If we execute 4 consecutive requests, with results 2,2,3 and 4 this will produce the following output. The Resource and InstrumentationScopeInfo data are ignored for brevity.

//...
name=hello.roll.dice,
description=A distribution of the value of the rolls.,      (1)
unit=points,
type=HISTOGRAM,
data=ImmutableHistogramData{
    aggregationTemporality=CUMULATIVE,                      (2)
    points=[
        ImmutableHistogramPointData{
            getStartEpochNanos=1720632058272341000,
            getEpochNanos=1720632068279567000,
            getAttributes={attribute.name="value"},         (3)
            getSum=11.0,       (4)
            getCount=4,        (5)
            hasMin=true,
            getMin=2.0,        (6)
            hasMax=true,
            getMax=4.0,        (7)
            getBoundaries=[1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0],   (8)
            getCounts=[0, 2, 1, 1, 0, 0, 0, 0],                  (9)
            getExemplars=[     (10)
                ImmutableDoubleExemplarData{
                    filteredAttributes={},
                    epochNanos=1720632063049392000,
                    spanContext=ImmutableSpanContext{
                        traceId=a22b43a600682ca7320516081eca998b,
                        spanId=645aa49f219181d0,
                        traceFlags=01,
                        traceState=ArrayBasedTraceState{entries=[]},
                        remote=false,
                        valid=true
                    },
                    value=2.0  (11)
                },
                //... exemplars for values 3 and 4 omitted for brevity
            ]
        }
    ]
}

1	The name, description and unit of the metric you defined in the constructor of the `HistogramResource` class.
2	The aggregation temporality of the histogram.
3	The attribute added to the histogram when the values were recorded.
4	The sum of the values recorded.
5	The number of values recorded.
6	The minimum value recorded.
7	The maximum value recorded.
8	The explicit bucket boundaries for the histogram.
9	The number of values recorded in each bucket.
10	The list of exemplars with tracing data for the values recorded. We only show 1 of 3 exemplars for brevity.
11	One of the 2 calls made with the value 2.

Differences with the Micrometer API

Timers and Distribution Summaries are not available in the OpenTelemetry API. Instead, use Histograms.
The OpenTelemetry API does not define annotations for metrics like Micrometer’s @Counted, @Timed or @MeterTag. You need to manually create the metrics.
OpenTelemetry uses their own Semantic Conventions to name metrics and attributes.

资源

See the main OpenTelemetry Guide resources section.

其他的植入(instrumentation)

Automatic metrics are not yet provided by the Quarkus OpenTelemetry extension. We plan to bridge the existing Quarkus Micrometer extension metrics to OpenTelemetry in the future.

Exporters

See the main OpenTelemetry Guide exporters section.

OpenTelemetry参考配置

See the main OpenTelemetry Guide configuration reference.

Using OpenTelemetry Metrics

先决条件

应用结构

解决方案

创建Maven项目

Examine the Jakarta REST resource

创建配置

运行应用程序

See the data

Grafana-OTel-LGTM Dev Service

Logging exporter

Start the application

Create your own metrics

OpenTelemetry Metrics vs Micrometer Metrics

Obtain a reference to the Meter

Use CDI Constructor injection

Member variable using the `@Inject` annotation

计数器（Counters）

Gauges

Histograms

Differences with the Micrometer API

资源

其他的植入(instrumentation)

Exporters

OpenTelemetry参考配置

Related content

On the same extensions

On the same topics

Using OpenTelemetry Metrics

先决条件

应用结构

解决方案

创建Maven项目

Examine the Jakarta REST resource

创建配置

运行应用程序

See the data

Grafana-OTel-LGTM Dev Service

Logging exporter

Start the application

Create your own metrics

OpenTelemetry Metrics vs Micrometer Metrics

Obtain a reference to the Meter

Use CDI Constructor injection

Member variable using the @Inject annotation

计数器（Counters）

Gauges

Histograms

Differences with the Micrometer API

资源

其他的植入(instrumentation)

Exporters

OpenTelemetry参考配置

Related content

On the same extensions

On the same topics

Member variable using the `@Inject` annotation