自动仪表化

使用Java进行自动仪表化使用一个可以附加到任何Java 8+应用程序的Java代理JAR。它动态注入字节码以捕获许多流行的库和框架的遥测数据。它可以用于捕获应用程序或服务的“边缘”处的遥测数据,如传入请求、传出HTTP调用、数据库调用等。要了解如何手动对服务或应用程序代码进行仪表化,请参阅手动仪表化

设置

  1. opentelemetry-java-instrumentation仓库的Releases中下载opentelemetry-javaagent.jar,并将JAR文件放置在您偏好的目录中。该JAR文件包含代理和仪表化库。

  2. -javaagent:path/to/opentelemetry-javaagent.jar和其他配置添加到JVM启动参数中,并启动您的应用程序:

    • 直接在启动命令中添加:

      java -javaagent:path/to/opentelemetry-javaagent.jar -Dotel.service.name=your-service-name -jar myapp.jar
      
    • 通过JAVA_TOOL_OPTIONS和其他环境变量添加:

      export JAVA_TOOL_OPTIONS="-javaagent:path/to/opentelemetry-javaagent.jar"
      export OTEL_SERVICE_NAME="your-service-name"
      java -jar myapp.jar
      

配置代理

代理具有高度可配置性。

一种选项是通过-D标志传递配置属性。在这个例子中,配置了服务名称和用于跟踪的Zipkin导出器:

java -javaagent:path/to/opentelemetry-javaagent.jar \
     -Dotel.service.name=your-service-name \
     -Dotel.traces.exporter=zipkin \
     -jar myapp.jar

您还可以使用环境变量配置代理:

OTEL_SERVICE_NAME=your-service-name \
OTEL_TRACES_EXPORTER=zipkin \
java -javaagent:path/to/opentelemetry-javaagent.jar \
     -jar myapp.jar

您还可以提供一个Java属性文件,并从中加载配置值:

java -javaagent:path/to/opentelemetry-javaagent.jar \
     -Dotel.javaagent.configuration-file=path/to/properties/file.properties \
     -jar myapp.jar

或者

OTEL_JAVAAGENT_CONFIGURATION_FILE=path/to/properties/file.properties \
java -javaagent:path/to/opentelemetry-javaagent.jar \
     -jar myapp.jar

要查看所有配置选项的完整范围,请参阅Agent Configuration

支持的库、框架、应用服务和JVM

Java代理附带了针对许多热门组件的仪表化库。完整列表请参阅[Supported libraries, frameworks, application services, and JVMs][支持]。

故障排除

您可以通过向代理传递-Dotel.javaagent.debug=true参数来查看调试日志。请注意,这些日志非常冗长。

下一步

在为您的应用程序或服务配置了自动仪表化之后,您可能希望注释选定的方法或添加手动仪表化以收集自定义的遥测数据。


Agent配置

注解

使用Java代理与仪表注解。

扩展

扩展可以添加代理的功能,而无需创建单独的分发文件。

最后修改 December 13, 2023: improve glossary translation (46f8201b)