Using OpenTelemetry

本指南解释了您的 Quarkus 应用程序如何利用 OpenTelemetry (OTel) 为交互式 Web 应用程序提供可观察性。

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

在这些页面上我们展示了扩展的信号无关特性。

On these page we show the signal independent features of the extension.

  • The old OpenTelemetry guide has been split into this generic guide, the OpenTelemetry Tracing Guide and the new OpenTelemetry Metrics Guide has been created.

  • OpenTelemetry Logging is not yet supported.

  • The use of the OpenTelemetry Agent is not needed nor recommended. Quarkus Extensions and the libraries they provide, are directly instrumented. That agent doesn’t work with native mode.

Introduction

OpenTelemetry 是一种可观测性框架和工具包，旨在创建和管理遥测数据，例如跟踪、指标和日志。至关重要的是，OpenTelemetry 与供应商和工具无关。

OpenTelemetry is an Observability framework and toolkit designed to create and manage telemetry data such as traces, metrics, and logs. Crucially, OpenTelemetry is vendor- and tool-agnostic.

Quarkus 为跟踪提供手动和自动检测功能，并为指标提供手动检测功能。

Quarkus provides manual and automatic instrumentation for tracing and manual instrumentation capabilities for metrics.

这将允许基于 Quarkus 的应用程序可供支持 OpenTelemetry 的工具和服务观测。

This will allow Quarkus based applications to be observable by tools and services supporting OpenTelemetry.

Quarkus 中的自动指标检测由 Quarkus Micrometer extension 完成。我们计划在将来为这些指标提供一个桥接器，以便它们也可以在 OpenTelemetry 中使用。

Automatic metrics instrumentation in Quarkus is done by the Quarkus Micrometer extension. We plan to provide, in the future, a bridge for those metrics to be available in OpenTelemetry as well.

Quarkus 支持 OpenTelemetry 自动配置。配置与你在 OpenTelemetry SDK Autoconfigure 可以看到的前缀 quarkus.* 匹配。

Quarkus supports the OpenTelemetry Autoconfiguration. The configurations match what you can see at OpenTelemetry SDK Autoconfigure with the quarkus.* prefix.

本指南对 OpenTelemetry 扩展进行了全面的解释，并说明了如何使用它。如果你需要有关任何特定信号（跟踪或指标）的详细信息，请参阅特定信号指南。

This guide provides a crosscutting explanation of the OpenTelemetry extension and how to use it. If you need details about any particular signal (tracing or metrics), please refer to the signal specific guide.

随着 OpenTelemetry 指标的引入，原始的单页指南必须根据信号类型进行拆分，如下所示：

With the introduction of OpenTelemetry Metrics, the original, single page guide had to be split according to signal types, as follows:

OpenTelemetry Tracing Guide

跟踪功能得到支持，并且 on 默认启用。

The tracing functionality is supported and on by default.

OpenTelemetry Metrics Guide

Enable Metrics

指标功能处于试验阶段，off 默认禁用。你需要通过设置以下内容来激活它：

The metrics functionality is experimental and off by default. You will need to activate it by setting:

quarkus.otel.metrics.enabled=true

在 application.properties 文件中的构建时。

At build time on your application.properties file.

Manual instrumentation only

目前仅支持手动检测。你可以使用 OpenTelemetry API 来创建和记录指标，但 Quarkus 尚未为指标提供自动检测。

For now only manual instrumentation is supported. You can use the OpenTelemetry API to create and record metrics but Quarkus is not yet providing automatic instrumentation for metrics.

在将来，我们计划在当前的 Micrometer 指标和 OpenTelemetry 之间建立桥接，并在可能的情况下保持兼容性。

In the future, we plan to bridge current Micrometer metrics to OpenTelemetry and maintain compatibility when possible.

Using the extension

如果你已有你的 Quarkus 项目，则可以通过在项目基本目录中运行以下命令向其添加 quarkus-opentelemetry 扩展：

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

Unresolved directive in opentelemetry.adoc - include::{includes}/devtools/extension-add.adoc[]

这会将以下内容添加到构建文件中：

This will add the following to your build file:

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-opentelemetry</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-opentelemetry")

Create the configuration

Unresolved directive in opentelemetry.adoc - include::{includes}/opentelemetry-config.adoc[]

Disable all or parts of the OpenTelemetry extension

一旦添加了依赖项，扩展将默认生成跟踪数据。要启用指标或全局禁用或部分禁用 OpenTelemetry 扩展，可以使用这些属性（它们是从下面的配置参考中提取的）：

Once you add the dependency, the extension will generate tracing data by default. To enable metrics or disable the OpenTelemetry extension globally or partially these are the properties to use (they are extracted from the config reference bellow):

Affected Signal Property name Default value Description

All

quarkus.otel.enabled

true

If false, disable the OpenTelemetry usage at build time.

All

quarkus.otel.sdk.disabled

false

Comes from the OpenTelemetry autoconfiguration. If true, will disable the OpenTelemetry SDK usage at runtime.

All output

quarkus.otel.exporter.otlp.enabled

true

Deprecated for removal.

If false will disable the default OTLP exporter at build time.

Traces

quarkus.otel.traces.enabled

true

If false, disable the OpenTelemetry tracing usage at build time.

Traces output

quarkus.otel.traces.exporter

cdi

List of exporters to be used for tracing, separated by commas. Has one of the values from ExporterType: otlp, cdi, none. This is a build time property and setting it to none will disable tracing data output.

Metrics

quarkus.otel.metrics.enabled

false

Metrics are disabled by default at build time because they are experimental.

Metrics output

quarkus.otel.metrics.exporter

cdi

List of exporters to be used for metrics, separated by commas. Has one of the values from ExporterType: otlp, cdi, none. This is a build time property and setting it to none will disable metrics data output.

如果您需要在运行时启用或禁用导出程序，可以使用 sampler，因为它能够在需要时过滤掉所有跨度。

If you need to enable or disable the exporter at runtime, you can use the sampler because it has the ability to filter out all the spans if needed.

跟踪中可以禁用特定的工具组件，比如忽略客户端请求但保留服务器请求。有关更多详细信息，请查看 OpenTelemetry Tracing Guide。

Particular instrumentation components can be disabled in tracing, like ignore client requests but keep server ones. For more details, please check the OpenTelemetry Tracing Guide.

Resource

resource 是正在生成遥测数据的实体的表征，它向导出的跟踪或指标添加属性以描述谁正在生成遥测数据。Quarkus 遵循 Java OpenTelemetry SDK 指定的 resources auto-configuration。

A resource is a representation of the entity that is producing telemetry, it adds attributes to the exported trace or metric to characterize who is producing the telemetry. Quarkus follows the resources auto-configuration specified by the Java OpenTelemetry SDK.

Default

以下属性默认添加到资源中。

The following attributes are added by default to resources.

Attribute name Content example Origin

service.name

"opentelemetry-quickstart"

Value comes from the artifactId, from the quarkus.application.name property or from quarkus.otel.resource.attributes=service.name=cart property.

host.name

"myHost"

Resolved at startup

service.version

"1.0-SNAPSHOT"

Resolved at build time from the artifact version

telemetry.sdk.language

"java"

Static value

telemetry.sdk.name

"opentelemetry"

Resolved at build time

telemetry.sdk.version

"1.32.0"

Resolved at build time

webengine.name

"Quarkus"

Static value

webengine.version

"999-SNAPSHOT"

Quarkus version resolved at build time

Using configuration

您可以通过设置 OpenTelemetry Configuration Reference 中描述的 quarkus.otel.resource.attributes 配置属性来添加其他属性。由于该属性可以在运行时被覆盖，因此 OpenTelemetry 扩展将按照 Quarkus Configuration Reference 中描述的优先顺序获取其值。

You can add additional attributes by setting the quarkus.otel.resource.attributes config property that is described in the OpenTelemetry Configuration Reference. Since this property can be overridden at runtime, the OpenTelemetry extension will pick up its value following the order of precedence that is described in the Quarkus Configuration Reference.

quarkus.otel.resource.attributes=deployment.environment=dev,service.name=cart,service.namespace=shopping

这将为 deployment.environment、 service.name 和 service.namespace 添加属性到资源中，并将其包含在跟踪和指标中。

This will add the attributes for deployment.environment, service.name and service.namespace to the resource and be included in traces and metrics.

Using CDI beans

如果您需要使用自定义资源或由 OpenTelemetry SDK Extensions 中的一个提供的资源，您可以创建多个资源生产者。OpenTelemetry 扩展将检测 Resource CDI Bean，并在配置 OTel SDK 时合并它们。

If by any means you need to use a custom resource or one that is provided by one of the OpenTelemetry SDK Extensions you can create multiple resource producers. The OpenTelemetry extension will detect the Resource CDI beans and will merge them when configuring the OTel SDK.

@ApplicationScoped
public class CustomConfiguration {

    @Produces
    @ApplicationScoped
    public Resource osResource() {
        return OsResource.get();
    }

    @Produces
    @ApplicationScoped
    public Resource ecsResource() {
        return EcsResource.get();
    }
}

Semantic conventions

OpenTelemetry 提供了一组 semantic conventions，用于标准化工具收集的数据。

OpenTelemetry provides a set of semantic conventions to standardize the data collected by the instrumentation.

在创建手动工具时，在命名指标或属性时，您应该遵循这些约定，而不是为表示现有约定的约定创建新名称。这将使跨服务的数据关联变得更容易执行。

When creating manual instrumentation, while naming metrics or attributes you should follow those conventions and not create new names to represent existing conventions. This will make data correlation easier to perform across services.

Exporters

Default

Quarkus OpenTelemetry 扩展使用自己基于 Vert.x 构建的信号导出程序，以实现最佳性能和可维护性。

The Quarkus OpenTelemetry extension uses its own signal exporters built on top of Vert.x for optimal performance and maintainability.

导出器会自动用 CDI 连接，这就是为什么 quarkus.otel.traces.exporter 和 quarkus.otel.metrics.exporter 属性默认为 cdi 的原因。

The exporter is automatically wired with CDI, that’s why the quarkus.otel.traces.exporter and quarkus.otel.metrics.exporter properties default to cdi.

quarkus.otel.exporter.otlp.protocol 默认为 grpc，但同样可以使用 http/protobuf。

The quarkus.otel.exporter.otlp.protocol defaults to grpc but http/protobuf can also be used.

如果你更改协议，也需要更改端点中的端口。grpc 的默认端口为 4317，http/protobuf 的默认端口为 4318。

If you change the protocol, you also need to change the port in the endpoint. The default port for grpc is 4317 and for http/protobuf is 4318.

On Quarkiverse

额外的导出器将在 Quarkiverse quarkus-opentelemetry-exporter 项目中提供。

Additional exporters will be available in the Quarkiverse quarkus-opentelemetry-exporter project.

目前，以下导出器可用（可能已过时）：

Currently, are available the following exporters (may be outdated) for:

  • Legacy Jaeger

  • Microsoft Azure

  • Google Cloud

在 Quarkiverse 上同样可用 Quarkus AWS SDK has integration with OpenTelemetry。

Also on Quarkiverse, the Quarkus AWS SDK has integration with OpenTelemetry.

Logging exporter (for debugging)

你可以将所有指标输出到控制台，用于调试/开发目的。

You can output all metrics to the console, for debugging/development purposes.

不要在生产环境中使用此功能。

Don’t use this in production.

你需要将以下依赖项添加到你的项目中：

You will need to add the following dependency to your project:

pom.xml
<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-exporter-logging</artifactId>
</dependency>
build.gradle
implementation("io.opentelemetry:opentelemetry-exporter-logging")

然后，在 application.properties 文件中设置导出器为 logging：

Then, setting the exporter to logging in the application.properties file:

quarkus.otel.metrics.exporter=logging 1
quarkus.otel.metric.export.interval=10000ms 2
quarkus.otel.traces.exporter=logging 3
1 Set the metrics 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.
3 Set the traces exporter to logging. Normally you don’t need to set this. The default is cdi.

Visualizing the data

我们建议使用 Getting Started with Grafana-OTel-LGTM。

We recommend the Getting Started with Grafana-OTel-LGTM.

这提供了一个使用“一体化” Grafana OTel LGTM的 Quarkus Dev 服务。

This provides a Quarkus Dev service using an "all-in-one" Grafana OTel LGTM.

Grafana 用于可视化数据，Loki 用于存储日志，Tempo 用于存储痕迹，Prometheus 用于存储指标。此外还提供了一个 OTel 收集器来接收数据。

Grafana is used to visualize data, Loki to store logs, Tempo to store traces and Prometheus to store metrics. Also provides and OTel collector to receive the data.

这提供了一种可视化应用程序生成的所有 OpenTelemetry 数据的简单方法。

This provides an easy way to visualize all OpenTelemetry data generated by the application.

你还可以使用 logging exporter 将所有痕迹和指标输出到控制台。

You can also use the logging-exporter-for-debugging to output all traces and metrics to the console.

OpenTelemetry Configuration Reference

Quarkus 支持痕迹中 OpenTelemetry 自动配置。这些配置与你在 OpenTelemetry SDK Autoconfigure 上看到的相同，并添加了通常的 quarkus.* 前缀。

Quarkus supports the OpenTelemetry Autoconfiguration for Traces. The configurations match what you can see at OpenTelemetry SDK Autoconfigure adding the usual quarkus.* prefix.

Quarkus OpenTelemetry 配置属性现在带有 quarkus.otel.* 前缀。

Quarkus OpenTelemetry configuration properties now have the quarkus.otel.* prefix.

Unresolved directive in opentelemetry.adoc - include::{generated-dir}/config/quarkus-opentelemetry.adoc[]