选择指南版本

Using OpenTelemetry Logging

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

这项技术被认为是preview。

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

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

OpenTelemetry Logging is considered tech preview and is disabled by default.
The OpenTelemetry Guide is available with signal independent information about the OpenTelemetry extension.

先决条件

完成这个指南，你需要:

大概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在容器中进行构建)

架构

In this guide, we create a straightforward REST application to demonstrate distributed logging, similar to the other OpenTelemetry guides.

解决方案

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

克隆 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.17.4: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

创建一个 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";
    }
}

If you have followed the tracing guide, this class will seem familiar. The main difference is that now, the hello message logged with org.jboss.logging.Logger will end up in the OpenTelemetry logs.

创建配置

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

quarkus.otel.logs.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.logs.enabled=true (2)
quarkus.otel.exporter.otlp.logs.endpoint=http://localhost:4317 (3)
quarkus.otel.exporter.otlp.logs.headers=authorization=Bearer my_secret (4)

1	All logs created from the application will include an OpenTelemetry `Resource` indicating the logs were created by the `myservice` application. If not set, it will default to the artifact id.
2	Enable the OpenTelemetry logging. Must be set at build time.
3	gRPC endpoint to send the logs. 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.

运行应用程序

First we need to start a system to visualise the OpenTelemetry data. We have 2 options:

Start an all-in-one Grafana OTel LGTM system for traces, metrics and logs.

See the data

Grafana OTel LGTM option

Take a look at: Getting Started with Grafana-OTel-LGTM.

This features a Quarkus Dev service including 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 logs to the console by setting the exporter to logging in the application.properties file:

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

1	Set the exporter to `logging`. Normally you don’t need to set this. The default is `cdi`.

Also add this dependency to your project:

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

OpenTelemetry参考配置

See the main OpenTelemetry Guide configuration reference.

先决条件
架构
解决方案
创建Maven项目
- Examine the Jakarta REST resource
- 创建配置
运行应用程序
- See the data
OpenTelemetry参考配置