opentelemetry-java-instrumentation翻译

原文地址:原文

 

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 propertyEnvironment variablePurpose
otel.exporterOTEL_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.

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 propertyEnvironment variableDescription
otel.exporter=otlp (default)OTEL_EXPORTER=otlpSelect the OpenTelemetry exporter (default)
otel.exporter.otlp.endpointOTEL_EXPORTER_OTLP_ENDPOINTThe OTLP endpoint to connect to. Default is localhost:55680.
otel.exporter.otlp.insecureOTEL_EXPORTER_OTLP_INSECUREWhether to enable client transport security for the connection
otel.exporter.otlp.headersOTEL_EXPORTER_OTLP_HEADERSKey-value pairs separated by semicolons to pass as request headers
otel.exporter.otlp.timeoutOTEL_EXPORTER_OTLP_TIMEOUTThe 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 propertyEnvironment variableDescription
otel.exporter=jaegerOTEL_EXPORTER=jaegerSelect the Jaeger exporter
otel.exporter.jaeger.endpointOTEL_EXPORTER_JAEGER_ENDPOINTThe Jaeger gRPC endpoint to connect to. Default is localhost:14250.
otel.exporter.jaeger.service.nameOTEL_EXPORTER_JAEGER_SERVICE_NAMEThe 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 propertyEnvironment variableDescription
otel.exporter=jaeger-thriftOTEL_EXPORTER=jaeger-thriftSelect the Jaeger HTTP Thrift exporter
otel.exporter.jaeger.endpointOTEL_EXPORTER_JAEGER_ENDPOINTThe Jaeger HTTP endpoint to send thrift data to. Default is http://localhost:14268/api/traces.
otel.exporter.jaeger.service.nameOTEL_EXPORTER_JAEGER_SERVICE_NAMEThe 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 propertyEnvironment variableDescription
otel.exporter=zipkinOTEL_EXPORTER=zipkinSelect the Zipkin exporter
otel.exporter.zipkin.endpointOTEL_EXPORTER_ZIPKIN_ENDPOINTThe Zipkin endpoint to connect to. Default is http://localhost:9411/api/v2/spans. Currently only HTTP is supported.
otel.exporter.zipkin.service.nameOTEL_EXPORTER_ZIPKIN_SERVICE_NAMEThe 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 propertyEnvironment variableDescription
otel.exporter=prometheusOTEL_EXPORTER=prometheusSelect the Prometheus exporter
otel.exporter.prometheus.portOTEL_EXPORTER_PROMETHEUS_PORTThe local port used to bind the prometheus metric server. Default is 9464.
otel.exporter.prometheus.hostOTEL_EXPORTER_PROMETHEUS_HOSTThe 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 propertyEnvironment variableDescription
otel.exporter=loggingOTEL_EXPORTER=loggingSelect the logging exporter
otel.exporter.logging.prefixOTEL_EXPORTER_LOGGING_PREFIXAn 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 propertyEnvironment variableDescription
otel.propagatorsOTEL_PROPAGATORSThe propagators to be used. Use a comma-separated list for multiple propagators. Supported propagators are tracecontextbaggageb3b3multijaegerottracer, and xray. Default is tracecontext,baggage (W3C).

OpenTelemetry Resource

OpenTelemetry Resource 是生产遥测数据实体的表示(representation)

The OpenTelemetry Resource is a representation of the entity producing telemetry.

System propertyEnvironment variableDescription
otel.resource.attributesOTEL_RESOURCE_ATTRIBUTESSpecify 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 propertyEnvironment variableDescription
otel.endpoint.peer.service.mappingOTEL_ENDPOINT_PEER_SERVICE_MAPPINGUsed 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 propertyEnvironment variableDescription
otel.bsp.schedule.delayOTEL_BSP_SCHEDULE_DELAYThe interval, in milliseconds, between two consecutive exports. Default is 5000.
otel.bsp.max.queueOTEL_BSP_MAX_QUEUEThe maximum queue size. Default is 2048.
otel.bsp.max.export.batchOTEL_BSP_MAX_EXPORT_BATCHThe maximum batch size. Default is 512.
otel.bsp.export.timeoutOTEL_BSP_EXPORT_TIMEOUTThe maximum allowed time, in milliseconds, to export data. Default is 30000.
otel.bsp.export.sampledOTEL_BSP_EXPORT_SAMPLEDWhether only sampled spans should be exported. Default is true.

Trace config

System propertyEnvironment variableDescription
otel.config.sampler.probabilityOTEL_CONFIG_SAMPLER_PROBABILITYSampling probability between 0 and 1. Default is 1.
otel.config.max.attrsOTEL_CONFIG_MAX_ATTRSThe maximum number of attributes per span. Default is 32.
otel.config.max.eventsOTEL_CONFIG_MAX_EVENTSThe maximum number of events per span. Default is 128.
otel.config.max.linksOTEL_CONFIG_MAX_LINKSThe maximum number of links per span. Default is 32
otel.config.max.event.attrsOTEL_CONFIG_MAX_EVENT_ATTRSThe maximum number of attributes per event. Default is 32.
otel.config.max.link.attrsOTEL_CONFIG_MAX_LINK_ATTRSThe maximum number of attributes per link. Default is 32.

Interval metric reader

System propertyEnvironment variableDescription
otel.imr.export.intervalOTEL_IMR_EXPORT_INTERVALThe 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)

warning 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 propertyEnvironment variablePurpose
trace.annotated.methods.excludeTRACE_ANNOTATED_METHODS_EXCLUDESuppress @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/FrameworkVersions
Akka HTTP10.0+
Apache HttpAsyncClient4.1+
Apache HttpClient2.0+
Armeria1.3+
AsyncHttpClient1.9+ (not including 2.x yet)
AWS Lambda1.0+
AWS SDK1.11.x and 2.2.0+
Cassandra Driver3.0+
Couchbase Client2.0+ (not including 3.x yet)
Dropwizard Views0.7+
Elasticsearch API5.0+ (not including 7.x yet)
Elasticsearch REST Client5.0+
Finatra2.9+
Geode Client1.4+
Google HTTP Client1.19+
Grizzly2.0+ (disabled by default)
gRPC1.5+
Hibernate3.3+
HttpURLConnectionJava 7+
http4k †3.270.0+
Hystrix1.4+
JAX-RS0.5+
JAX-RS Client2.0+
JDBCJava 7+
Jedis1.4+
JMS1.1+
JSP2.3+
Kafka0.11+
khttp0.1+
Kubernetes Client7.0+
Lettuce4.0+ (not including 6.x yet)
Log4j 11.2+
Log4j 22.7+
Logback1.0+
MongoDB Drivers3.3+
Netty3.8+
OkHttp3.0+
Play2.3+ (not including 2.8.x yet)
Play WS1.0+
RabbitMQ Client2.7+
Ratpack1.4+
Reactor3.1+
Reactor Netty0.9+ (not including 1.0)
Rediscala1.8+
Redisson3.0+
RMIJava 7+
RxJava1.0+
Servlet2.2+
Spark Web Framework2.3+
Spring Batch3.0+
Spring Data1.8+
Spring Scheduling3.1+
Spring Web MVC3.1+
Spring Webflux5.0+
Spymemcached2.12+
Struts22.3+
Twilio6.6+ (not including 8.x yet)
Vert.x3.0+
Vert.x RxJava23.5+

† OpenTelemetry support provided by the library

这里是支持的应用服务器:

These are the supported application servers:

Application serverVersionJVMOS
Glassfish5.0.x, 5.1.xOpenJDK 8, 11Ubuntu 18, Windows Server 2019
JBoss EAP7.1.x, 7.3.xOpenJDK 8, 11Ubuntu 18, Windows Server 2019
Jetty9.4.x, 10.0.x, 11.0.xOpenJDK 8, 11Ubuntu 20
Payara5.0.x, 5.1.xOpenJDK 8, 11Ubuntu 18, Windows Server 2019
Tomcat7.0.x, 8.5.x, 9.0.x, 10.0.xOpenJDK 8, 11Ubuntu 18
Weblogic12OpenJDK 8Oracle Linux 7, 8
Weblogic14OpenJDK 8, 11Oracle Linux 7, 8
WildFly13.0.xOpenJDK 8Ubuntu 18, Windows Server 2019
WildFly17.0.1, 21.0.0OpenJDK 8, 11Ubuntu 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.

Roadmap to 1.0 (GA)

See GA Requirements

Contributing

See CONTRIBUTING.md.

Approvers (@open-telemetry/java-instrumentation-approvers):

Maintainers (@open-telemetry/java-instrumentation-maintainers):

Learn more about roles in the community repository.

Thanks to all the people who already contributed!

  • 1
    点赞
  • 6
    收藏
    觉得还不错? 一键收藏
  • 0
    评论

“相关推荐”对你有帮助么?

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值