入门指南
本页面将向您展示如何在Java中使用OpenTelemetry开始工作。
您将学习如何自动地为简单的Java应用程序进行仪表化,以便将跟踪、指标和日志发送到控制台。
先决条件
确保在本地安装了以下内容:
- Java JDK
- Gradle
示例应用程序
下面的示例使用了一个基本的Spring Boot应用程序。如果您不使用Spring Boot,那没关系 —— 您也可以在其他Web框架中使用OpenTelemetry Java,例如Apache Wicket和Play。有关受支持框架的完整列表,请参阅注册表。
有关更详细的示例,请参阅examples。
依赖项
首先,在一个名为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.SpringApplication;
import org.springframework.boot.Banner;
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浏览器中打开http://localhost:8080/rolldice以确保它正常工作。
gradle assemble
java -jar ./build/libs/java-simple.jar
仪表化
接下来,您将使用一个Java代理在启动时自动仪表化应用程序。虽然您可以[配置Java代理][]的多种方式,但下面的步骤使用环境变量。
-
从opentelemetry-java-instrumentation存储库的Releases中下载opentelemetry-javaagent.jar。该JAR文件包含代理和所有自动仪表化包:
curl -L -O https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar
请注意JAR文件的路径。 -
设置和导出变量,指定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
重要
请将上述PATH/TO
替换为您的JAR文件路径。 -
再次运行应用程序:
$ 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.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}}
...
下一步是什么?
了解更多:
- 使用其他导出器为遥测数据运行此示例。
- 尝试在自己的应用程序上进行自动仪表化。
- 对于轻量级定制遥测,尝试使用注解。
- 了解[手动仪表化][]并尝试更多示例。
- 查看OpenTelemetry演示,其中包括基于Java的广告服务和基于Kotlin的欺诈检测服务