返回指南

按版本

编辑此页面

使用 OpenTelemetry Logging

本指南解释了您的 Quarkus 应用程序如何利用 OpenTelemetry (OTel) 为交互式 Web 应用程序提供结构化、上下文相关、供应商中立和集中式日志记录。

此技术被认为是预览版。

在预览版中，不保证向后兼容性和生态系统中的存在。具体的改进可能需要更改配置或 API，并且成为稳定版的计划正在进行中。欢迎在我们的邮件列表中或在我们的 GitHub 问题跟踪器中提供反馈。

有关可能的完整状态列表，请查看我们的常见问题解答条目。

本文档是 Quarkus 可观察性参考指南的一部分，该指南介绍了此组件和其他可观察性相关组件。

OpenTelemetry 日志被认为是技术预览版，默认情况下处于禁用状态。
OpenTelemetry 指南提供了关于 OpenTelemetry 扩展的独立于信号的信息。

先决条件

要完成本指南，您需要

大约 15 分钟
一个 IDE
已安装 JDK 17+ 并正确配置了 JAVA_HOME
Apache Maven 3.9.9
Docker 和 Docker Compose 或 Podman，以及 Docker Compose
如果您想使用它，可以选择 Quarkus CLI
如果您想构建本机可执行文件（或者如果您使用本机容器构建，则为 Docker），可以选择安装 Mandrel 或 GraalVM 并进行适当的配置

架构

在本指南中，我们将创建一个简单的 REST 应用程序来演示 OTel 日志记录，类似于其他 OpenTelemetry 信号指南。

解决方案

我们建议您按照以下部分的说明逐步创建应用程序。但是，您可以直接跳到完成的示例。

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

解决方案位于 opentelemetry-quickstart 目录中。

创建 Maven 项目

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

CLI

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

要创建 Gradle 项目，请添加 --gradle 或 --gradle-kotlin-dsl 选项。

有关如何安装和使用 Quarkus CLI 的更多信息，请参阅 Quarkus CLI 指南。

Maven

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

要创建 Gradle 项目，请添加 -DbuildTool=gradle 或 -DbuildTool=gradle-kotlin-dsl 选项。

对于 Windows 用户

如果使用 cmd，（不要使用反斜杠 \ 并将所有内容放在同一行上）
如果使用 Powershell，请将 -D 参数用双引号括起来，例如 "-DprojectArtifactId=opentelemetry-quickstart"

此命令生成 Maven 项目并导入 quarkus-opentelemetry 扩展，其中包括默认的 OpenTelemetry 支持和一个用于 OTLP 的 gRPC span exporter。

如果您已经配置了 Quarkus 项目，则可以通过在项目基本目录中运行以下命令将 quarkus-opentelemetry 扩展添加到您的项目中

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")

检查 Jakarta REST 资源

创建一个 src/main/java/org/acme/opentelemetry/TracedResource.java 文件，内容如下

package org.acme.opentelemetry;

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")
public class TracedResource {

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

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {
        LOG.info("hello");
        return "hello";
    }
}

如果您遵循了跟踪指南，那么此类看起来会很熟悉。主要区别在于，现在使用 org.jboss.logging.Logger 记录的 hello 消息将最终出现在 OpenTelemetry 日志中。

创建配置

OpenTelemetry 日志记录的唯一强制配置是启用它的配置

quarkus.otel.logs.enabled=true

要更改任何默认属性值，这是一个关于如何在应用程序中配置默认 OTLP gRPC Exporter 的示例，使用 src/main/resources/application.properties 文件

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

1	从应用程序创建的所有日志将包括一个 OpenTelemetry `Resource`，指示日志是由 `myservice` 应用程序创建的。如果未设置，则默认为 artifact id。
2	启用 OpenTelemetry 日志记录。必须在构建时设置。
3	用于发送日志的 gRPC 端点。如果未设置，则默认为 `https://:4317`。
4	通常用于身份验证的可选 gRPC 标头。

要使用相同的属性配置所有信号的连接，请查看 OpenTelemetry 指南的基本配置部分。

设置日志级别

默认情况下，导出所有日志级别。

如果在 application.properties 文件中创建以下配置，则只会导出级别为 ERROR 或更高的日志

quarkus.otel.logs.level=ERROR

与 Quarkus 中的其他日志一样，日志级别可以设置为这些值。

运行应用程序

首先，我们需要启动一个系统来可视化 OpenTelemetry 数据。我们有 2 个选项

启动一个用于跟踪、指标和日志的一体化 Grafana OTel LGTM 系统。

查看数据

Grafana OTel LGTM 选项

请查看：Grafana-OTel-LGTM 入门。

此功能包含一个 Quarkus Dev 服务，包括一个用于可视化数据的 Grafana、一个用于存储日志的 Loki、一个用于存储跟踪的 Tempo 和一个用于存储指标的 Prometheus。还提供一个 OTel 收集器来接收数据。

日志记录导出器

您可以通过在 application.properties 文件中将导出器设置为 logging 来将所有日志输出到控制台

quarkus.otel.logs.exporter=logging (1)

1	将导出器设置为 `logging`。通常您不需要设置此项。默认值为 `cdi`。

还将此依赖项添加到您的项目中

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

OpenTelemetry 配置参考

请参阅主要的 OpenTelemetry 指南配置参考。

先决条件
架构
解决方案
创建 Maven 项目
- 检查 Jakarta REST 资源
- 创建配置
运行应用程序
- 查看数据
OpenTelemetry 配置参考