通过示例入门

5 分钟内为你的应用接入遥测数据！

本页面将向你展示如何在 Java 中快速开始使用 OpenTelemetry。

你将学习如何为一个简单的 Java 应用实现自动插桩， 通过这样的方式使链路、指标和日志输出到控制台。

前置条件

确保你已在本地安装以下内容：

示例应用

以下示例使用一个基础的 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);  } }

使用以下命令构建并运行应用程序，然后在网页浏览器中打开 http://localhost:8080/rolldice 以确认其正常运行。

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

插桩

接下来，你将使用 Java 代理在启动时对应用进行自动插桩。 虽然你可以通过多种方式配置 Java 代理，但以下步骤将使用环境变量。

  1. 从 opentelemetry-java-instrumentation 仓库的 发布（页面） 下载 opentelemetry-javaagent.jar。 该 JAR 文件包含代理程序及所有自动插桩包：

    curl -L -O https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

  2. 设置并导出指定 Java 代理 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

  3. 再次运行你的应用：

    $ java -jar ./build/libs/java-simple.jar ...

    留意 otel.javaagent 的输出信息。

  4. 从另一个终端中，使用 curl 发送请求：

    curl localhost:8080/rolldice

  5. 停止服务器进程。

在步骤 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.io/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}} ...

接下来做什么？

更多内容:


Last modified September 10, 2025: [zh] Update content/zh/docs/languages/java/*.md (#7720) (2e1f53e0)