原文地址:原文
OpenTelemetry Instrumentation for Java
这个项目提供了一个Java agent JAR,这个jar可以attached to任何Java8+的应用上,动态地注入(inject)字节码从大量的流行库和框架(popular libraries and frameworks)中捕捉遥测数据。你可以以多种格式导出遥测数据。你也可以通过命令行或环境变量来配置agent和exporter。最终的结果就是:在不用修改Java Application代码的情况下,获取遥测数据的能力。
(This project provides a Java agent JAR that can be attached to any Java 8+ application and dynamically injects bytecode to capture telemetry from a number of popular libraries and frameworks. You can export the telemetry data in a variety of formats. You can also configure the agent and exporter via command line arguments or environment variables. The net result is the ability to gather telemetry data from a Java application without code changes.)
开始
(Download the latest version.)
这个包包含了instrumentation agent和支持的库的instrumentation,以及所有data exporter。此包提供了一个完全自动化的,开箱即用的体验。使用-javaagent命令启动 instrumentation agent:
(This package includes the instrumentation agent as well as instrumentations for all supported libraries and all available data exporters. The package provides a completely automatic, out-of-the-box experience.
Enable the instrumentation agent using the -javaagent
flag to the JVM.)
java -javaagent:path/to/opentelemetry-javaagent-all.jar \
-jar myapp.jar
默认情况下,OpenTelemetry Java agent使用配置好的OTLP exporter来通过localhost:55680端口
发送数据到 OpenTelemetry collector中。配置参数通过Java系统属性-D或者环境变量来传递,下文有完整的环境变量列表。例如:
(By default, the OpenTelemetry Java agent uses OTLP exporter configured to send data to OpenTelemetry collector at localhost:55680
.
Configuration parameters are passed as Java system properties (-D
flags) or as environment variables. See below for a full list of environment variables. For example:)
java -javaagent:path/to/opentelemetry-javaagent-all.jar \
-Dotel.exporter=zipkin \
-jar myapp.jar
通过系统属性 otel.exporter.jar
来指定external exporter的jar文件:
(Specify the external exporter JAR file using the otel.exporter.jar
system property:)
java -javaagent:path/to/opentelemetry-javaagent-all.jar \
-Dotel.exporter.jar=path/to/external-exporter.jar \
-jar myapp.jar
如何添加自定义instrumentation可见 Manually Instrumenting 部分。
(Learn how to add custom instrumentation in the Manually Instrumenting section.)
配置参数(可能会发生变化!)
注意:这些参数名很有可能随着时间发生变化,所以当尝试新版本的时候请回到此处检查。如果你发现了任何bug或者程序发生了unexpected的行为,请报告给我们。
(Note: These parameter names are very likely to change over time, so please check back here when trying out a new version! Please report any bugs or unexpected behavior you find.)
Exporters
下面是所有exporters共有的配置属性:
The following configuration properties are common to all exporters:
System property | Environment variable | Purpose |
---|---|---|
otel.exporter | OTEL_EXPORTER | 将被使用的exporter,如果有多个,使用逗号分隔;目前并不支持多个metric的exporter,默认值是otlp The exporter to be used. Use a comma-separated list for multiple exporters. Currently does not support multiple metric exporters. Default is |
OTLP exporter(同时是span和metric的exporter)
OTLP exporter (both span and metric exporters)
一个opentelemetry-java的OTLP span和metric exporter的简单wrapper如下。
A simple wrapper for the OpenTelemetry Protocol (OTLP) span and metric exporters of opentelemetry-java.
System property | Environment variable | Description |
---|---|---|
otel.exporter=otlp (default) | OTEL_EXPORTER=otlp | Select the OpenTelemetry exporter (default) |
otel.exporter.otlp.endpoint | OTEL_EXPORTER_OTLP_ENDPOINT | The OTLP endpoint to connect to. Default is localhost:55680 . |
otel.exporter.otlp.insecure | OTEL_EXPORTER_OTLP_INSECURE | Whether to enable client transport security for the connection |
otel.exporter.otlp.headers | OTEL_EXPORTER_OTLP_HEADERS | Key-value pairs separated by semicolons to pass as request headers |
otel.exporter.otlp.timeout | OTEL_EXPORTER_OTLP_TIMEOUT | The maximum waiting time allowed to send each batch. Default is 1000 . |
如果想要配置OTLP exporter的服务名,添加service.name的key到OpenTelemetry Resource (见下文),例如:OTEL_RESOURCE_ATTRIBUTES=service.name=myservice
To configure the service name for the OTLP exporter, add the service.name
key to the OpenTelemetry Resource (see below), e.g. OTEL_RESOURCE_ATTRIBUTES=service.name=myservice
.
Jaeger exporter
一个简单的Jaeger exporter of opentelemetry-java的wrapper,这个exporter使用gRPC作为它的通信协议。
(A simple wrapper for the Jaeger exporter of opentelemetry-java. This exporter uses gRPC for its communications protocol.)
System property | Environment variable | Description |
---|---|---|
otel.exporter=jaeger | OTEL_EXPORTER=jaeger | Select the Jaeger exporter |
otel.exporter.jaeger.endpoint | OTEL_EXPORTER_JAEGER_ENDPOINT | The Jaeger gRPC endpoint to connect to. Default is localhost:14250 . |
otel.exporter.jaeger.service.name | OTEL_EXPORTER_JAEGER_SERVICE_NAME | The service name of this JVM instance. Default is unknown . |
Jaeger Thrift over HTTP exporter
一个 Jaeger exporter的简单wrapper,使用http协议上的Thrift编码格式。
A simple wrapper for the Jaeger exporter, but using Thrift encoded payloads over HTTP.
System property | Environment variable | Description |
---|---|---|
otel.exporter=jaeger-thrift | OTEL_EXPORTER=jaeger-thrift | Select the Jaeger HTTP Thrift exporter |
otel.exporter.jaeger.endpoint | OTEL_EXPORTER_JAEGER_ENDPOINT | The Jaeger HTTP endpoint to send thrift data to. Default is http://localhost:14268/api/traces . |
otel.exporter.jaeger.service.name | OTEL_EXPORTER_JAEGER_SERVICE_NAME | The service name of this JVM instance. Default is unknown . |
Zipkin exporter
一个Zipkin exporter的简单wrapper,使用http协议上的JSON编码格式。
A simple wrapper for the Zipkin exporter of opentelemetry-java. It sends JSON in Zipkin format to a specified HTTP URL.
System property | Environment variable | Description |
---|---|---|
otel.exporter=zipkin | OTEL_EXPORTER=zipkin | Select the Zipkin exporter |
otel.exporter.zipkin.endpoint | OTEL_EXPORTER_ZIPKIN_ENDPOINT | The Zipkin endpoint to connect to. Default is http://localhost:9411/api/v2/spans . Currently only HTTP is supported. |
otel.exporter.zipkin.service.name | OTEL_EXPORTER_ZIPKIN_SERVICE_NAME | The service name of this JVM instance. Default is unknown . |
Prometheus exporter
一个 Prometheus exporter 的简单wrapper
A simple wrapper for the Prometheus exporter of opentelemetry-java.
System property | Environment variable | Description |
---|---|---|
otel.exporter=prometheus | OTEL_EXPORTER=prometheus | Select the Prometheus exporter |
otel.exporter.prometheus.port | OTEL_EXPORTER_PROMETHEUS_PORT | The local port used to bind the prometheus metric server. Default is 9464 . |
otel.exporter.prometheus.host | OTEL_EXPORTER_PROMETHEUS_HOST | The local address used to bind the prometheus metric server. Default is 0.0.0.0 . |
Logging exporter
这个logger exporter打印span的名称和属性到stdout,它主要用于test和debug。
The logging exporter prints the name of the span along with its attributes to stdout. It's mainly used for testing and debugging.
System property | Environment variable | Description |
---|---|---|
otel.exporter=logging | OTEL_EXPORTER=logging | Select the logging exporter |
otel.exporter.logging.prefix | OTEL_EXPORTER_LOGGING_PREFIX | An optional string printed in front of the span name and attributes. |
Propagator
Propagator决定了使用哪个分布式tracing header格式,和baggage propagation header 格式。
The propagators determine which distributed tracing header formats are used, and which baggage propagation header formats are used.
System property | Environment variable | Description |
---|---|---|
otel.propagators | OTEL_PROPAGATORS | The propagators to be used. Use a comma-separated list for multiple propagators. Supported propagators are tracecontext , baggage , b3 , b3multi , jaeger , ottracer , and xray . Default is tracecontext,baggage (W3C). |
OpenTelemetry Resource
OpenTelemetry Resource 是生产遥测数据实体的表示(representation)
The OpenTelemetry Resource is a representation of the entity producing telemetry.
System property | Environment variable | Description |
---|---|---|
otel.resource.attributes | OTEL_RESOURCE_ATTRIBUTES | Specify resource attributes in the following format: key1=val1,key2=val2,key3=val3 |
Peer service name
peer service name是正在连接中的远程服务名。它对应于 Resource 中对应的本地服务。
The peer service name is the name of a remote service being connected to. It corresponds to service.name
in the Resource for the local service.
System property | Environment variable | Description |
---|---|---|
otel.endpoint.peer.service.mapping | OTEL_ENDPOINT_PEER_SERVICE_MAPPING | Used to specify a mapping from hostnames or IP addresses to peer services, as a comma-separated list of host=name pairs. The peer service is added as an attribute to a span whose host or IP match the mapping. For example, if set to 1.2.3.4=cats-service,dogs-abcdef123.serverlessapis.com=dogs-api, requests to 1.2.3.4 will have a peer.service attribute of cats-service and requests to dogs-abcdef123.serverlessapis.com will have an attribute of dogs-api . |
Batch span processor
System property | Environment variable | Description |
---|---|---|
otel.bsp.schedule.delay | OTEL_BSP_SCHEDULE_DELAY | The interval, in milliseconds, between two consecutive exports. Default is 5000 . |
otel.bsp.max.queue | OTEL_BSP_MAX_QUEUE | The maximum queue size. Default is 2048 . |
otel.bsp.max.export.batch | OTEL_BSP_MAX_EXPORT_BATCH | The maximum batch size. Default is 512 . |
otel.bsp.export.timeout | OTEL_BSP_EXPORT_TIMEOUT | The maximum allowed time, in milliseconds, to export data. Default is 30000 . |
otel.bsp.export.sampled | OTEL_BSP_EXPORT_SAMPLED | Whether only sampled spans should be exported. Default is true . |
Trace config
System property | Environment variable | Description |
---|---|---|
otel.config.sampler.probability | OTEL_CONFIG_SAMPLER_PROBABILITY | Sampling probability between 0 and 1. Default is 1 . |
otel.config.max.attrs | OTEL_CONFIG_MAX_ATTRS | The maximum number of attributes per span. Default is 32 . |
otel.config.max.events | OTEL_CONFIG_MAX_EVENTS | The maximum number of events per span. Default is 128 . |
otel.config.max.links | OTEL_CONFIG_MAX_LINKS | The maximum number of links per span. Default is 32 |
otel.config.max.event.attrs | OTEL_CONFIG_MAX_EVENT_ATTRS | The maximum number of attributes per event. Default is 32 . |
otel.config.max.link.attrs | OTEL_CONFIG_MAX_LINK_ATTRS | The maximum number of attributes per link. Default is 32 . |
Interval metric reader
System property | Environment variable | Description |
---|---|---|
otel.imr.export.interval | OTEL_IMR_EXPORT_INTERVAL | The interval, in milliseconds, between pushes to the exporter. Default is 60000 . |
个性化OpenTelemetry SDK
个性化SDK是非常高级的行为,目前还在原型阶段。它可能发生巨大的改变甚至完全移除,使用时需要非常小心。
The OpenTelemetry API 暴露了 SPI hooks 来进行个性化,例如 attached to spans或者Sampler的Resource
因为自动化检测运行时所处的classpath不同于 instrumented application,所以不可能customization in the application to take advantage of this customization。为了提供这样的个性化,你可以提供一个JAR文件,并且使用系统属性 otel.initializer.jar来实现SPI接口。注意,这个JAR需要shade同样使用agent方式的
OpenTelemetry API。最简单的实现方式是使用同这里一样的shading配置。另外,你必须指定io.opentelemetry.javaagent.shaded.io.opentelemetry.api.trace.spi.TraceProvider的值为已经实现了SPI接口的类名称。
Customizing the SDK is highly advanced behavior and is still in the prototyping phase. It may change drastically or be removed completely. Use with caution
The OpenTelemetry API exposes SPI hooks for customizing its behavior, such as the Resource
attached to spans or the Sampler
.
Because the automatic instrumentation runs in a different classpath than the instrumented application, it is not possible for customization in the application to take advantage of this customization. In order to provide such customization, you can provide the path to a JAR file, including an SPI implementation using the system property otel.initializer.jar
. Note that this JAR needs to shade the OpenTelemetry API in the same way as the agent does. The simplest way to do this is to use the same shading configuration as the agent from here. In addition, you must specify the io.opentelemetry.javaagent.shaded.io.opentelemetry.api.trace.spi.TraceProvider
to the name of the class that implements the SPI.
手动检测(Manually instrumenting)
starting with 0.6.0, and prior to version 1.0.0,
opentelemetry-javaagent-all.jar
only supports manual instrumentation using theopentelemetry-api
version with the same version number as the Java agent you are using. Starting with 1.0.0, the Java agent will start supporting multiple (1.0.0+) versions ofopentelemetry-api
.
您需要在opentelemetry api库上添加一个依赖项才能开始使用;如果您更倾向使用@WithSpan注解,也可以包含(引入)opentelemetry-extension-annotations依赖。
You'll need to add a dependency on the opentelemetry-api
library to get started; if you intend to use the @WithSpan
annotation, also include the opentelemetry-extension-annotations
dependency.
Maven
<dependencies>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-api</artifactId>
<version>0.11.0</version>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-extension-annotations</artifactId>
<version>0.11.0</version>
</dependency>
</dependencies>
Gradle
dependencies {
implementation('io.opentelemetry:opentelemetry-api:0.11.0')
implementation('io.opentelemetry:opentelemetry-extension-annotations:0.11.0')
}
给当前span添加属性值(Adding attributes to the current span)
检测(instrument)应用时一个常见需求是捕获特定应用或特定业务的信息,将其作为附加属性(additional attributes)追加到自动检测中已经存在的span中。使用Span.current()和setAttribute()来获取当前span:
A common need when instrumenting an application is to capture additional application-specific or business-specific information as additional attributes to an existing span from the automatic instrumentation. Grab the current span with Span.current()
and use the setAttribute()
methods:
import io.opentelemetry.api.trace.Span;
// ...
Span span = Span.current();
span.setAttribute(..., ...);
使用@WithSpan给方法创建span(Creating spans around methods with @WithSpan)
另外一个常见场景是在一个已经存在的第一方代码方法上捕获span。使用@WithSpan注解简单粗暴:
Another common situation is to capture a span around an existing first-party code method. The @WithSpan
annotation makes this straightforward:
import io.opentelemetry.extension.annotations.WithSpan;
public class MyClass {
@WithSpan
public void MyLogic() {
<...>
}
}
每次应用invoke被注解的方法,都会创建一个span,这个span代表着方法执行的过程并提供了任何被抛出的异常。除非给注解指定参数,否则span的名称将会是<className>.<methodName>
Each time the application invokes the annotated method, it creates a span that denote its duration and provides any thrown exceptions. Unless specified as an argument to the annotation, the span name will be <className>.<methodName>
.
Suppressing @WithSpan
instrumentation
如果你使用@WithSpan对代码进行了过度检测,并且希望在不修改代码的情况下抑制(suppress)其中一些代码,那么Suppressing @WithSpan是很有用的。
Suppressing @WithSpan
is useful if you have code that is over-instrumented using @WithSpan
and you want to suppress some of them without modifying the code.
System property | Environment variable | Purpose |
---|---|---|
trace.annotated.methods.exclude | TRACE_ANNOTATED_METHODS_EXCLUDE | Suppress @WithSpan instrumentation for specific methods. |
Format is "my.package.MyClass1[method1,method2];my.package.MyClass2[method3]" |
(使用Tracer来手动创建span)Creating spans manually with a Tracer
OpenTelemetry 提供了tracer使应用中自定义检测更加简单。查看 OpenTelemetry Java QuickStart 中如何配置tracer的例子,学习如何使用Tracer,Scope and Span 接口来检测你的应用。
OpenTelemetry offers a tracer to easily enable custom instrumentation throughout your application. See the OpenTelemetry Java QuickStart for an example of how to configure the tracer and use the Tracer, Scope and Span interfaces to instrument your application.
支持的libraries,frameworks和应用服务器(Supported libraries, frameworks, and application servers)
这里是支持的libraries 和 frameworks:
These are the supported libraries and frameworks:
† OpenTelemetry support provided by the library
这里是支持的应用服务器:
These are the supported application servers:
Application server | Version | JVM | OS |
---|---|---|---|
Glassfish | 5.0.x, 5.1.x | OpenJDK 8, 11 | Ubuntu 18, Windows Server 2019 |
JBoss EAP | 7.1.x, 7.3.x | OpenJDK 8, 11 | Ubuntu 18, Windows Server 2019 |
Jetty | 9.4.x, 10.0.x, 11.0.x | OpenJDK 8, 11 | Ubuntu 20 |
Payara | 5.0.x, 5.1.x | OpenJDK 8, 11 | Ubuntu 18, Windows Server 2019 |
Tomcat | 7.0.x, 8.5.x, 9.0.x, 10.0.x | OpenJDK 8, 11 | Ubuntu 18 |
Weblogic | 12 | OpenJDK 8 | Oracle Linux 7, 8 |
Weblogic | 14 | OpenJDK 8, 11 | Oracle Linux 7, 8 |
WildFly | 13.0.x | OpenJDK 8 | Ubuntu 18, Windows Server 2019 |
WildFly | 17.0.1, 21.0.0 | OpenJDK 8, 11 | Ubuntu 18, Windows Server 2019 |
关闭的检测(Disabled instrumentations)
有些检测会产生过多的spans,使得trace非常noisy。因此,下面这些instrumentations默认是关闭的:
Some instrumentations can produce too many spans and make traces very noisy. For this reason, the following instrumentations are disabled by default:
jdbc-datasource
which creates spans whenever thejava.sql.DataSource#getConnection
method is called.
如果想打开他们,otel.instrumentation.<name>.enabled,系统变量:
-Dotel.instrumentation.jdbc-datasource.enabled=true
To enable them, add the otel.instrumentation.<name>.enabled
system property: -Dotel.instrumentation.jdbc-datasource.enabled=true
Grizzly instrumentation
当你使用Grizzly作为Servlet-based应用时,你可以从特定Servlet支持中获取更好的体验。因为这两个检测相互冲突,Grizzly HTTP Server的更generic的检测将默认被关闭。如果需要,你可以通过添加系统属性: -Dotel.instrumentation.grizzly.enabled=true来打开它。
When you use Grizzly for Servlet-based applications, you get better experience from Servlet-specific support. As these two instrumentations conflict with each other, more generic instrumentation for Grizzly HTTP server is disabled by default. If needed, you can enable it by adding the following system property: -Dotel.instrumentation.grizzly.enabled=true
Suppress特定的自动检测(Suppressing specific auto-instrumentation)
See Suppressing specific auto-instrumentation
Logger MDC auto-instrumentation
See Logger MDC auto-instrumentation
排除故障(Troubleshooting)
打开agent的内部debug日志:
To turn on the agent's internal debug logging:
-Dotel.javaagent.debug=true
注意:这些日志都是特别冗长的,只有在需要的时候打开它。打开debug日志将会对应用性能产生负面影响。
Note: These logs are extremely verbose. Enable debug logging only when needed. Debug logging negatively impacts the performance of your application.
Roadmap to 1.0 (GA)
See GA Requirements
Contributing
See CONTRIBUTING.md.
Approvers (@open-telemetry/java-instrumentation-approvers):
- John Watson, Splunk
- Mateusz Rzeszutek, Splunk
Maintainers (@open-telemetry/java-instrumentation-maintainers):
- Anuraag Agrawal, AWS
- Nikita Salnikov-Tarnovski, Splunk
- Trask Stalnaker, Microsoft
- Tyler Benson, DataDog
Learn more about roles in the community repository.
Thanks to all the people who already contributed!