通过示例入门

在不到 5 分钟内为您的应用获取遥测数据！

本页将向您展示如何在 Java 中开始使用 OpenTelemetry。

您将学习如何自动仪器化一个简单的 Java 应用程序，以便跟踪、指标和日志能够输出到控制台。

先决条件

请确保您已在本地安装以下软件

Java JDK 17+（因为使用了 Spring Boot 3）；否则为 Java 8+
Gradle

示例应用程序

以下示例使用了一个基本的 Spring Boot 应用程序。您也可以使用其他 Web 框架，如 Apache Wicket 或 Play。有关支持的库和框架的完整列表，请参阅注册表。

有关更详细的示例，请参阅示例。

依赖项

要开始，请在一个名为 java-simple 的新目录中设置环境。在该目录中，创建一个名为 build.gradle.kts 的文件，其中包含以下内容：

plugins {
  id("java")
  id("org.springframework.boot") version "3.0.6"
  id("io.spring.dependency-management") version "1.1.0"
}

sourceSets {
  main {
    java.setSrcDirs(setOf("."))
  }
}

repositories {
  mavenCentral()
}

dependencies {
  implementation("org.springframework.boot:spring-boot-starter-web")
}

创建并启动 HTTP 服务器

在同一个文件夹中，创建一个名为 DiceApplication.java 的文件，并将以下代码添加到该文件中：

package otel;

import org.springframework.boot.Banner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DiceApplication {
  public static void main(String[] args) {
    SpringApplication app = new SpringApplication(DiceApplication.class);
    app.setBannerMode(Banner.Mode.OFF);
    app.run(args);
  }
}

创建另一个名为 RollController.java 的文件，并将以下代码添加到该文件中：

package otel;

import java.util.Optional;
import java.util.concurrent.ThreadLocalRandom;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class RollController {
  private static final Logger logger = LoggerFactory.getLogger(RollController.class);

  @GetMapping("/rolldice")
  public String index(@RequestParam("player") Optional<String> player) {
    int result = this.getRandomNumber(1, 6);
    if (player.isPresent()) {
      logger.info("{} is rolling the dice: {}", player.get(), result);
    } else {
      logger.info("Anonymous player is rolling the dice: {}", result);
    }
    return Integer.toString(result);
  }

  public int getRandomNumber(int min, int max) {
    return ThreadLocalRandom.current().nextInt(min, max + 1);
  }
}

使用以下命令构建并运行应用程序，然后在 Web 浏览器中打开 https://:8080/rolldice 以确保其正常工作。

gradle assemble
java -jar ./build/libs/java-simple.jar

仪表

接下来，您将使用 Java Agent 在启动时自动对应用程序进行仪器化。虽然您可以通过多种方式配置 Java Agent，但下面的步骤将使用环境变量。

从 opentelemetry-java-instrumentation 存储库的 Releases 下载 opentelemetry-javaagent.jar。该 JAR 文件包含 Agent 和所有自动仪器化包。
```
curl -L -O https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
```
注意 JAR 文件的路径。
设置并导出指定 Java Agent JAR 和控制台导出器的变量，使用适合您的 shell/终端环境的表示法——我们举例说明了 bash 类 shell 的表示法。
```
export JAVA_TOOL_OPTIONS="-javaagent:PATH/TO/opentelemetry-javaagent.jar" \
  OTEL_TRACES_EXPORTER=logging \
  OTEL_METRICS_EXPORTER=logging \
  OTEL_LOGS_EXPORTER=logging \
  OTEL_METRIC_EXPORT_INTERVAL=15000
```
重要提示
- 将上面 `PATH/TO` 替换为您的 JAR 文件路径。
- 将 OTEL_METRIC_EXPORT_INTERVAL 设置为一个远低于默认值的值，如上所示，**仅在测试期间**，以便您能更快地确保指标已正确生成。
再次运行您的应用程序
```
$ java -jar ./build/libs/java-simple.jar
...
```
注意 otel.javaagent 的输出。
从另一个终端，使用 curl 发送请求
```
curl localhost:8080/rolldice
```
停止服务器进程。

在步骤 4 中，您应该会看到来自服务器和客户端的跟踪和日志输出，看起来像这样（为了方便阅读，跟踪输出已换行）。

[otel.javaagent 2023-04-24 17:33:54:567 +0200] [http-nio-8080-exec-1] INFO
io.opentelemetry.exporter.logging.LoggingSpanExporter - 'RollController.index' :
 70c2f04ec863a956e9af975ba0d983ee 7fd145f5cda13625 INTERNAL [tracer:
 io.opentelemetry.spring-webmvc-6.0:1.25.0-alpha] AttributesMap{data=
 {thread.id=39, thread.name=http-nio-8080-exec-1}, capacity=128,
 totalAddedValues=2}
[otel.javaagent 2023-04-24 17:33:54:568 +0200] [http-nio-8080-exec-1] INFO
io.opentelemetry.exporter.logging.LoggingSpanExporter - 'GET /rolldice' :
70c2f04ec863a956e9af975ba0d983ee 647ad186ad53eccf SERVER [tracer:
io.opentelemetry.tomcat-10.0:1.25.0-alpha] AttributesMap{
  data={user_agent.original=curl/7.87.0, net.host.name=localhost,
  net.transport=ip_tcp, http.target=/rolldice, net.sock.peer.addr=127.0.0.1,
  thread.name=http-nio-8080-exec-1, net.sock.peer.port=53422,
  http.route=/rolldice, net.sock.host.addr=127.0.0.1, thread.id=39,
  net.protocol.name=http, http.status_code=200, http.scheme=http,
  net.protocol.version=1.1, http.response_content_length=1,
  net.host.port=8080, http.method=GET}, capacity=128, totalAddedValues=17}

在步骤 5 中，停止服务器时，您应该会看到所有收集到的指标的输出（指标输出已换行并缩短以便于查看）。

[otel.javaagent 2023-04-24 17:34:25:347 +0200] [PeriodicMetricReader-1] INFO
io.opentelemetry.exporter.logging.LoggingMetricExporter - Received a collection
 of 19 metrics for export.
[otel.javaagent 2023-04-24 17:34:25:347 +0200] [PeriodicMetricReader-1] INFO
io.opentelemetry.exporter.logging.LoggingMetricExporter - metric:
ImmutableMetricData{resource=Resource{schemaUrl=
https://opentelemetry.org.cn/schemas/1.19.0, attributes={host.arch="aarch64",
host.name="OPENTELEMETRY", os.description="Mac OS X 13.3.1", os.type="darwin",
process.command_args=[/bin/java, -jar, java-simple.jar],
process.executable.path="/bin/java", process.pid=64497,
process.runtime.description="Homebrew OpenJDK 64-Bit Server VM 20",
process.runtime.name="OpenJDK Runtime Environment",
process.runtime.version="20", service.name="java-simple",
telemetry.auto.version="1.25.0", telemetry.sdk.language="java",
telemetry.sdk.name="opentelemetry", telemetry.sdk.version="1.25.0"}},
instrumentationScopeInfo=InstrumentationScopeInfo{name=io.opentelemetry.runtime-metrics,
version=1.25.0, schemaUrl=null, attributes={}},
name=process.runtime.jvm.buffer.limit, description=Total capacity of the buffers
in this pool, unit=By, type=LONG_SUM, data=ImmutableSumData{points=
[ImmutableLongPointData{startEpochNanos=1682350405319221000,
epochNanos=1682350465326752000, attributes=
{pool="mapped - 'non-volatile memory'"}, value=0, exemplars=[]},
ImmutableLongPointData{startEpochNanos=1682350405319221000,
epochNanos=1682350465326752000, attributes={pool="mapped"},
value=0, exemplars=[]},
ImmutableLongPointData{startEpochNanos=1682350405319221000,
epochNanos=1682350465326752000, attributes={pool="direct"},
value=8192, exemplars=[]}], monotonic=false, aggregationTemporality=CUMULATIVE}}
...

下一步？

更多信息

使用另一个导出器来运行此示例，以获取遥测数据。
尝试将零代码仪器化应用到您自己的应用程序上。
对于轻量级的自定义遥测，请尝试注解。
了解手动仪器化并尝试更多示例。
查看 OpenTelemetry 演示，其中包含基于 Java 的 Ad Service 和基于 Kotlin 的 Fraud Detection Service。

Feedback

这个页面有用吗？

谢谢。您的反馈受到赞赏！

请让我们知道我们如何改进此页面。您的反馈受到赞赏！

最后修改于 2025 年 6 月 24 日：将 prettier 从 3.5.3 升级到 3.6.0 (#7170) (0930994d)