opentelemetry-java-instrumentation翻译

关注

原创 2022-08-03 21:43:49 3.9k 阅读 AI 写同款· GEO 优化 ›

.NET可观测性实战：OpenTelemetry+Serilog+Prometheus全链路监控可观测性是现代分布式系统稳定运行的核心能力，其本质是通过日志、指标、链路追踪三大支柱，实现对系统内部状态的可推断性。其底层原理依赖统一上下文传播（如Trace ID）、标准化语义约定（OpenTelemetry Logs/Metrics/Tracing规范）与低侵入采集机制。技术价值在于将模糊的‘系统变慢’转化为可定位的‘HttpClient第3次重试耗时2.1秒’，显著缩短MTTR。典型应用场景涵盖ASP.NET Core微服务、BackgroundService后台任务及EF Core数据访问层的全栈监阅读详情

原文地址：原文

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

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，如果有多个，使用逗号分隔；目前并不支持多个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.

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 the opentelemetry-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 of opentelemetry-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:

Library/Framework	Versions
Akka HTTP	10.0+
Apache HttpAsyncClient	4.1+
Apache HttpClient	2.0+
Armeria	1.3+
AsyncHttpClient	1.9+ (not including 2.x yet)
AWS Lambda	1.0+
AWS SDK	1.11.x and 2.2.0+
Cassandra Driver	3.0+
Couchbase Client	2.0+ (not including 3.x yet)
Dropwizard Views	0.7+
Elasticsearch API	5.0+ (not including 7.x yet)
Elasticsearch REST Client	5.0+
Finatra	2.9+
Geode Client	1.4+
Google HTTP Client	1.19+
Grizzly	2.0+ (disabled by default)
gRPC	1.5+
Hibernate	3.3+
HttpURLConnection	Java 7+
http4k †	3.270.0+
Hystrix	1.4+
JAX-RS	0.5+
JAX-RS Client	2.0+
JDBC	Java 7+
Jedis	1.4+
JMS	1.1+
JSP	2.3+
Kafka	0.11+
khttp	0.1+
Kubernetes Client	7.0+
Lettuce	4.0+ (not including 6.x yet)
Log4j 1	1.2+
Log4j 2	2.7+
Logback	1.0+
MongoDB Drivers	3.3+
Netty	3.8+
OkHttp	3.0+
Play	2.3+ (not including 2.8.x yet)
Play WS	1.0+
RabbitMQ Client	2.7+
Ratpack	1.4+
Reactor	3.1+
Reactor Netty	0.9+ (not including 1.0)
Rediscala	1.8+
Redisson	3.0+
RMI	Java 7+
RxJava	1.0+
Servlet	2.2+
Spark Web Framework	2.3+
Spring Batch	3.0+
Spring Data	1.8+
Spring Scheduling	3.1+
Spring Web MVC	3.1+
Spring Webflux	5.0+
Spymemcached	2.12+
Struts2	2.3+
Twilio	6.6+ (not including 8.x yet)
Vert.x	3.0+
Vert.x RxJava2	3.5+

† 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 the java.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.