Using OpenTelemetry

本指南解释了您的 Quarkus 应用程序如何利用 OpenTelemetry (OTel) 为交互式 Web 应用程序提供可观察性。 在这些页面上我们展示了扩展的信号无关特性。

  • 旧 OpenTelemetry 指南已拆分为该通用指南、OpenTelemetry Tracing Guide 和新创建的 OpenTelemetry Metrics Guide。

  • OpenTelemetry 日志尚未得到支持。

  • 使用 Quarkus 扩展及其提供的库，它们会直接被检测。该代理无法与本机模式配合使用。

Introduction

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

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

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

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

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

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

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

OpenTelemetry Tracing Guide

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

OpenTelemetry Metrics Guide

Enable Metrics

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

quarkus.otel.metrics.enabled=true

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

Manual instrumentation only

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

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

Using the extension

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

CLI
quarkus extension add {add-extension-extensions}
Maven
./mvnw quarkus:add-extension -Dextensions='{add-extension-extensions}'
Gradle
./gradlew addExtension --extensions='{add-extension-extensions}'

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

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

Create the configuration

扩展程序不需要任何强制配置即可工作。

默认情况下，导出程序将使用 gRPC 协议和端点 http://localhost:4317 批量发送数据。

如果您需要更改任何默认属性值，这里有一个示例，说明如何使用 src/main/resources/application.properties 文件在应用程序中配置默认 OTLP gRPC 导出程序：

quarkus.application.name=myservice (1)
quarkus.otel.exporter.otlp.endpoint=http://localhost:4317 (2)
quarkus.otel.exporter.otlp.headers=authorization=Bearer my_secret (3)
quarkus.log.console.format=%d{HH:mm:ss} %-5p traceId=%X{traceId}, parentId=%X{parentId}, spanId=%X{spanId}, sampled=%X{sampled} [%c{2.}] (%t) %s%e%n  (4)

# Alternative to the console log
quarkus.http.access-log.pattern="...traceId=%{X,traceId} spanId=%{X,spanId}" (5)
1 从应用程序创建的所有遥测数据都将包含一个 OpenTelemetry Resource 属性，表示遥测数据是由 myservice 应用程序创建的。如果未设置，它将默认为项目工件 ID。
2 用于发送遥测数据的 gRPC 端点。如果未设置，它将默认为 http://localhost:4317 。
3 通常用于身份验证的可选 gRPC 标头
4 将跟踪信息添加到日志消息。
5 您也可以只将跟踪信息放入访问日志中。在这种情况下，您必须省略控制台日志格式中的信息。

我们为连接相关属性提供了信号无关的配置，这意味着在以下情况下可以同时使用相同的属性进行跟踪和度量：

quarkus.otel.exporter.otlp.endpoint=http://localhost:4317

如果您需要对每个信号使用不同的配置，则可以使用特定属性：

quarkus.otel.exporter.otlp.traces.endpoint=http://trace-uri:4317 (1)
quarkus.otel.exporter.otlp.metrics.endpoint=http://metrics-uri:4317 (2)
1 跟踪导出器的端点。
2 指标导出器的端点。

Disable all or parts of the OpenTelemetry extension

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

Affected Signal Property name Default value Description

All

quarkus.otel.enabled

true

如果为 false，则在 build 时禁用 OpenTelemetry 使用。

All

quarkus.otel.sdk.disabled

false

来自 OpenTelemetry 自动配置。如果为 true，将在 runtime 禁用 OpenTelemetry SDK 使用。

All output

quarkus.otel.exporter.otlp.enabled

true

弃用以供移除。如果为 false，将在 build 时间禁用默认 OTLP 导出程序。

Traces

quarkus.otel.traces.enabled

true

如果为 false，将在 build 时间禁用 OpenTelemetry 跟踪使用。

Traces output

quarkus.otel.traces.exporter

cdi

用于跟踪的导出程序列表，以逗号分隔。具有来自 ExporterType 中的值之一： otlp、 cdi、 none。这是一个 build 时间属性，将其设置为 none 将禁用跟踪数据输出。

Metrics

quarkus.otel.metrics.enabled

false

由于是实验性的，已在 build 时间默认禁用指标。

Metrics output

quarkus.otel.metrics.exporter

cdi

用于指标的导出程序列表，以逗号分隔。具有来自 ExporterType 中的值之一： otlp、 cdi、 none。这是一个 build 时间属性，将其设置为 none 将禁用指标数据输出。

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

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

Resource

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

Default

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

Attribute name Content example Origin

service.name

"opentelemetry-quickstart"

值来自 artifactId，来自 quarkus.application.name 属性或来自 quarkus.otel.resource.attributes=service.name=cart 属性。

host.name

"myHost"

Resolved at startup

service.version

"1.0-SNAPSHOT"

在构建时从工件版本解析

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 版本

Using configuration

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

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

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

Using CDI beans

如果您需要使用自定义资源或由 OpenTelemetry SDK Extensions 中的一个提供的资源，您可以创建多个资源生产者。OpenTelemetry 扩展将检测 Resource CDI Bean，并在配置 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，用于标准化工具收集的数据。

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

Exporters

Default

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

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

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

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

On Quarkiverse

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

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

  • Legacy Jaeger

  • Microsoft Azure

  • Google Cloud

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

Logging exporter (for debugging)

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

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

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

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

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

quarkus.otel.metrics.exporter=logging 1
quarkus.otel.metric.export.interval=10000ms 2
quarkus.otel.traces.exporter=logging 3
1 将指标导出器设置为 logging。在正常情况下，无需设置此项。默认值为 cdi。
2 设置导出指标的时间间隔。默认值为 1m，对于调试来说这个间隔太长了。
3 将痕迹导出器设置为 logging。在正常情况下，无需设置此项。默认值为 cdi。

Visualizing the data

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

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

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

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

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

OpenTelemetry Configuration Reference

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

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

Unresolved include directive in modules/ROOT/pages/opentelemetry.adoc - include::../../../target/quarkus-generated-doc/config/quarkus-opentelemetry.adoc[]