›

支持的技术

编辑

支持的技术编辑

Elastic APM Java 代理会自动检测各种 API、框架和应用服务器。本节列出了所有受支持的技术。

如果我们尚不支持您喜欢的技术，您可以通过参与我们的调查来投票。我们将根据结果添加对请求最多的技术的支持。

其他选择包括向代理的公共 API 添加依赖项，以便以编程方式创建自定义事务和跨度，或者创建您自己的插件来检测您想要检测的技术。

如果您想扩展代理的自动检测功能，贡献指南可以帮助您入门。

例如，如果您选择的 HTTP 客户端库未列出，则表示不会为这些传出的 HTTP 请求创建跨度。如果您使用的 Web 框架不受支持，则代理不会捕获事务。

Java 版本编辑

从 1.33.0 版本开始，Java 7 支持已被弃用，并将在未来版本中移除

供应商	支持的版本	备注
Oracle JDK	7u60+*, 8u40+, 9, 10, 11, 17, 21	`--module-path` 尚未经过测试
OpenJDK	7u60+*, 8u40+, 9, 10, 11, 17, 21	`--module-path` 尚未经过测试
IBM J9 VM	8 服务刷新 5+（内部版本 2.9 或 8.0.5.0）	不支持基于采样的分析器
HP-UX JVM	7.0.10+*, 8.0.02+
SAP JVM	8.1.065+

* Java 7 支持已被弃用，并将在未来版本中移除

早期 Java 8 和 Java 7

不支持更新 40 之前的早期 Java 8 版本，因为它们存在一些错误，当 Java 代理处于活动状态时，可能会导致 JVM 崩溃，因此代理在这些版本上将无法启动。同样，更新 60 之前的 Java 7 版本也不受支持，因为它们在 invokedynamic 方面存在错误。

以下是发生这种情况时显示的消息示例。

Failed to start agent - JVM version not supported: 1.8.0_31 Java HotSpot(TM) 64-Bit Server VM 25.31-b07.
To override Java version verification, set the 'elastic.apm.disable_bootstrap_checks' System property,
or the `ELASTIC_APM_DISABLE_BOOTSTRAP_CHECKS` environment variable, to 'true'.

如本消息所述，如果需要，您可以通过向 JVM 参数添加 -Delastic.apm.disable_bootstrap_checks=true 或为 JVM 环境变量设置 ELASTIC_APM_DISABLE_BOOTSTRAP_CHECKS=true 来禁用此检查。

Web 框架编辑

框架	支持的版本	描述	自
Servlet API	3+	将为到基于 Servlet API 的应用程序的所有传入 HTTP 请求创建一个事务。从 1.18.0 版本开始，如果 servlet 通过 `forward` 或 `include` API 将执行调度到另一个 servlet 或错误页面，则会创建额外的跨度。另请参阅应用服务器/Servlet 容器	1.0.0，4.0+（`jakarta.servlet`）自 1.28.0 起
Spring Web MVC	4.x、5.x、6.x	如果您使用的是 Spring MVC（例如，使用 Spring Boot），则事务将根据您的控制器（`ControllerClass#controllerMethod`）命名。	1.0.0，6.x 自 1.38.0 起
Spring Webflux	5.2.3+	为传入的 HTTP 请求创建事务，支持带注释的端点和函数式端点。	1.24.0（实验性），1.34.0（GA），6.1+ 自 1.45.0 起
JavaServer Faces	2.2.x、2.3.x、3.0.x	如果您使用的是 JSF，则事务将根据请求的 Facelets 命名，并且会捕获跨度以了解执行和渲染情况	1.0.0，`jakarta.faces` 自 1.28.0 起
Spring Boot	1.5+、2.x、3.x	支持嵌入式 Tomcat、Jetty 和 Undertow	1.0.0，3.x 自 1.38.0 起
JAX-RS	2.x、3.x	事务将根据您的资源（`ResourceClass#resourceMethod`）命名。请注意，仅扫描 `application_packages` 中配置的包以查找 JAX-RS 资源。但是，如果您未设置此选项，则会扫描所有类。但这会增加启动时间。注意：仅在受支持的应用服务器/Servlet 容器上运行时才支持 JAX-RS。	1.0.0，`jakarta.ws.rs` 自 1.28.0 起
JAX-WS		事务将根据您的 `@javax.jws.WebService`、`@jakarta.jws.WebService` 注释类和 `@javax.jws.WebMethod`、`@jakarta.jws.WebMethod` 注释方法名称（`WebServiceClass#webMethod`）命名。请注意，仅扫描 `application_packages` 中配置的包以查找 JAX-WS 资源。但是，如果您未设置此选项，则会扫描所有类。但这会增加启动时间。注意：仅在受支持的应用服务器/Servlet 容器上运行并使用 HTTP 绑定时才支持 JAX-WS。	1.4.0，`jakarta.jws` 自 1.28.0 起
Grails	3+		1.17.0
Apache Struts	2.x	事务将根据您的操作（`ActionClass#actionMethod`）命名。	1.24.0
Vert.x Web	3.6+	将传入的 HTTP 请求捕获为事务	1.24.0（实验性）
Sparkjava（不是 Apache Spark）	2.x	事务将根据您的路由（`GET /foo/:bar`）命名。	1.25.0
com.sun.net.httpserver.HttpServer	1.7+	将传入的 HTTP 请求捕获为事务	1.25.0
Javalin	3.13.8+		1.25.0
Java API for WebSocket	1.0	将使用 `@OnOpen`、`@OnMessage`、`@OnError` 或 `@OnClose` 注释的方法捕获为使用 `@ServerEndpoint` 注释的类的事务。	1.29.0

应用服务器/Servlet 容器编辑

Elastic APM Java 代理对 Servlet API 3+ 提供了通用支持。但是，某些服务器需要特殊处理。此处列出的服务器已通过集成测试套件进行测试，以确保 Elastic APM 与它们兼容。其他符合 Servlet 3+ 的服务器很可能也能正常工作。

服务器	支持的版本
Tomcat	7.x、8.5.x、9.x、10.x
WildFly	8+
JBoss EAP	6.4、7.x
Jetty（仅支持 `ServletContextHandler`）	9.2, 9.3, 9.4
WebSphere Liberty	8.5.5、18.0.x
Undertow Servlet	1.4
Payara	4.x、5.x
Oracle WebLogic	12.2

数据存储编辑

数据库	支持的版本	描述	自
JDBC	4.1+	代理会自动为您的所有 JDBC 查询创建数据库跨度。这包括由 O/R 映射器（如 Hibernate）执行的 JDBC 查询。注意：确保您的 JDBC 驱动程序至少是为 Java 1.4 编译的。不支持使用较低版本编译的驱动程序。也不支持 IBM DB2 db2jcc 驱动程序。请更新到 db2jcc4。	1.0.0
Elasticsearch Java REST 和 API 客户端	5.0.2+	代理会自动为通过官方 REST 客户端完成的查询创建 Elasticsearch 跨度。	1.0.0，异步自 1.5.0 起，API 客户端自 1.32.0 起
Hibernate Search	5.x（默认启用），6.x（默认禁用）	代理会自动为通过 Hibernate Search API 完成的查询创建 Hibernate Search 跨度。注意：此功能在 6.x 版本中标记为实验性功能，这意味着默认情况下它是关闭的。要启用此功能，请将 `disable_instrumentations` ( [1.0.0] 在 1.0.0 中添加。自 1.15.0 版本起，可以在运行时更改此值 ) 配置选项设置为空字符串	1.9.0
Redis Jedis	1.4.0-5.x	代理会为与 Jedis 客户端的交互创建跨度。	1.10.0，4+ 自 1.31.0 起
Redis Lettuce	3.4+	代理会为与 Lettuce 客户端的交互创建跨度。	1.13.0
Redis Redisson	2.1.5+	代理会为与 Redisson 客户端的交互创建跨度。	1.15.0
MongoDB 驱动程序	3.x	代理会为与 MongoDB 驱动程序的交互创建跨度。目前，仅支持同步驱动程序 (mongo-java-driver)。当前不支持异步和反应式驱动程序。跨度的名称为 `<db>.<collection>.<command>`。不会记录实际的查询。	1.12.0
MongoDB 同步驱动程序	4.x	代理会为与 MongoDB 4.x 同步驱动程序的交互创建跨度。这为 `org.mongodb:mongodb-driver-sync` 提供了支持	1.34.0
Cassandra	2.x+	代理会为与 Cassandra Datastax 驱动程序的交互创建跨度。这为 `com.datastax.cassandra:cassandra-driver-core` 和 `com.datastax.oss:java-driver-core` 提供了支持	1.23.0
AWS DynamoDB	1.x、2.x	代理会为通过 AWS Java SDK 与 AWS DynamoDb 服务的交互创建跨度。	1.31.0，2.21+ 自 1.44.0 起
AWS S3	1.x、2.x	代理会为通过 AWS Java SDK 与 AWS S3 服务的交互创建跨度。	1.31.0，2.21+ 自 1.44.0 起

网络框架编辑

只有使用受支持的网络框架之一，分布式跟踪才能工作。

对于受支持的 HTTP 库，代理会自动为传出的 HTTP 请求创建 span 并传播跟踪标头。span 以 <method> <host> 模式命名，例如 GET elastic.co。

框架	支持的版本	注意	自
Apache HttpClient	4.3+		0.7.0 (4.3+) 1.8.0 (4.0+) 1.45.0 (5.0+)
Apache HttpClient（旧版）	3.0+	需要将 `instrument_ancient_bytecode` 设置为 `true`	1.35.0
Apache HttpAsyncClient	4.0+		1.6.0
Spring RestTemplate	3.1.1+		0.7.0
OkHttp	2、3、4（自 1.22.0 起支持 4.4+）		1.4.0（通过 `Call#execute()` 进行同步调用）1.5.0（通过 `Call#enquene(Callback)` 进行异步调用）
HttpUrlConnection			1.4.0
JAX-WS 客户端		通过 `javax.xml.ws.Service` 创建的 JAX-WS 客户端本身支持上下文传播，因为它们在底层使用 `HttpUrlConnection`。	1.4.0
AsyncHttpClient	2.x		1.7.0
Apache Dubbo	2.x，但 2.7.0、2.7.1、2.7.2 和低于 2.5.0 的版本除外		1.17.0
JDK 11 HttpClient			1.18.0
Vert.x WebClient	3.6+		1.25.0
Spring Webclient	5.2.3+		1.33.0（实验性），1.34.0（正式版）
Finagle Http Client	22+		1.35.0
LdapClient			1.36.0
Spring RestClient	6.1.0+		1.45.0

异步框架编辑

当 Span 在与其父级不同的线程中创建时，跟踪上下文必须传播到该线程。

本节列出了所有受支持的异步框架。

框架	支持的版本	描述	自
`ExecutorService`		代理会传播 `ExecutorService` 的上下文。	1.4.0
`ScheduledExecutorService`		代理会传播 `ScheduledExecutorService#schedule` 的上下文（这不包括 `scheduleAtFixedRate` 或 `scheduleWithFixedDelay`。	1.17.0
`ForkJoinPool`		代理会传播 `ForkJoinPool` 的上下文。	1.17.0
Scala Future	2.13.x	代理在使用 `scala.concurrent.Future` 或 `scala.concurrent.Promise` 时传播上下文。它将在使用链接方法（如 `map`、`flatMap`、`traverse` 等）时传播上下文。注意：要启用 Scala Future 支持，您需要启用实验性插件。	1.18.0
Reactor	3.2.x+	代理会传播 `Flux` 和 `Mono` 的上下文。	1.24.0（实验性），1.34.0（正式版）

消息框架编辑

使用消息框架时，会传播发送方上下文，以便将接收方事件关联到同一跟踪。

框架	支持的版本	描述	自
JMS	1.1, 2.0	代理将 JMS 发送和接收捕获为 span/事务	自 1.13.0 起支持 `javax.jms`，自 1.40.0 起支持 `jakarta.jms`
Kafka	<0.11.0 - 不支持分布式跟踪；0.11.0+ - 完全支持	代理会捕获 Kafka 记录发送和轮询。Kafka 流不会被跟踪。	1.13.0
RabbitMQ	3.x - 5.x	代理会捕获 RabbitMQ 消息发送、消费和轮询	1.20.0
AWS SQS	1.x、2.x	代理会捕获 SQS 消息发送和轮询，以及通过 JMS 发送和消费的 SQS 消息。	1.34.0，自 1.44.0 起支持 2.21+

分布式跟踪编辑

消息系统客户端的 Java 代理检测包括发送方和接收方。当检测到的客户端在跟踪的事务中发送消息时，会创建一个 send span。此外，如果消息系统支持消息/记录标头/注释，则代理会添加 tracecontext 标头以启用分布式跟踪。

在接收方，检测到的客户端将尝试以几种方式之一创建适当的分布式跟踪链接，具体取决于如何接收消息

被动消息处理： 当通过实现被动消息侦听器 API（例如 javax.jms.MessageListener#onMessage）应用消息处理逻辑时，创建接收方事务非常简单，因为检测到的 API 方法调用封装了消息处理。尽管如此，仍需考虑两种用例
- 单消息处理： 当消息侦听器 API 接受单个消息时，代理会为每个接收到的消息创建一个 messaging 类型的交易，作为对应于接收到的消息的 send span 的子交易，并使用相同的跟踪 ID
- 批量消息处理： 当消息侦听器 API 接受一批消息时（例如 org.springframework.amqp.core.MessageListener.onMessageBatch），代理默认情况下会创建一个根交易（即与任何 send span 不同的跟踪 ID）来封装整个批处理。批处理交易的类型为 messaging，包含指向批处理中消息对应的所有 send span 的链接*。这可以通过（未记录的）message_batch_strategy 配置选项进行更改，该选项接受 BATCH_HANDLING（默认）或 SINGLE_HANDLING 来启用为每个消息创建一个子交易。
主动消息轮询： 在某些情况下，消息是通过主动轮询从代理消费的。每当在已有活动 span 时发生轮询操作时，代理都会创建一个 poll span，并为轮询操作返回的每个包含 tracecontext 标头的消息添加 span 链接*。由于此类轮询 API 没有提供任何有关消息处理实际发生时间的指示，因此代理需要应用一些试探法来跟踪消息处理。在这种类型的消息接收中，还需要考虑两种用例
- 轮询返回单个消息： 在这种情况下，代理可能会对执行消息处理逻辑的线程应用假设，以确定处理何时开始和结束。基于此，它将为每个已消费的消息创建一个交易。如果已消费的消息包含 tracecontext 标头，则 receive 交易将是相应 send span 的子交易。
- 轮询返回消息批处理： 通常，在这种情况下，代理将包装消息集合并依赖实际迭代来为每个消息创建一个交易，作为相应 send span 的子交易，并且作为同一跟踪的一部分。如果迭代发生在已有活动 span 时，则代理会为每个消息 send span 添加一个指向活动（父）span 的链接*，而不是为每个消息创建交易/span。

* 自 8.3 版起，APM 服务器和 Kibana 支持 Span 链接，自 1.32.0 版起，Java 代理支持 Span 链接

RabbitMQ 特性编辑

使用轮询时，context.message.queue.name 字段将包含队列名称，否则包含交换名称。
context.message.destination.resource 字段将包含 rabbitmq/XXX，其中 XXX 是交换名称。

某些交换/队列名称已标准化，以保持低基数和用户友好性 - 默认交换用 <default> 表示。 - null 交换标准化为 <unknown>，例如在没有消息的情况下进行轮询时。 - 名称以 amq.gen- 开头的生成队列标准化为 amq.gen-*。

调度框架编辑

使用调度框架时，将为每次执行创建一个交易。

框架支持的版本描述自

框架	支持的版本	描述	自
调度注释		代理会检测在 `application_packages` 中配置的包中定义并使用以下任一注释进行注释的任何方法：`org.springframework.scheduling.annotation.Scheduled` `org.springframework.scheduling.annotation.Schedules` `javax.ejb.Schedule` `javax.ejb.Schedules` `jakarta.ejb.Schedule` `jakarta.ejb.Schedules`，以便创建一个类型为 `scheduled` 的交易，表示已调度的任务执行	1.6.0，自 1.28.0 起支持 `jakarta.ejb.Schedule`
Quartz	1.0+	代理会检测实现 `org.quartz.Job` 的任何类的 `execute` 方法，以及扩展 `org.springframework.scheduling.quartz.QuartzJobBean` 的任何类的 `executeInternal` 方法，并创建一个类型为 `scheduled` 的交易，表示作业执行注意：只有来自 quartz-jobs 依赖项的类才会被自动检测。对于其他作业的检测，必须将包添加到 `application_packages` 参数中。	1.8.0 - 2.0+ 1.26.0 - 1.0+
TimerTask		代理会检测在 `application_packages` 中配置的包中扩展 `java.util.TimerTask` 的任何类的 `run` 方法，并创建一个类型为 `scheduled` 的交易，表示作业执行	1.18.0

调度注释

代理会检测在 application_packages 中配置的包中定义并使用以下任一注释进行注释的任何方法：org.springframework.scheduling.annotation.Scheduled org.springframework.scheduling.annotation.Schedules javax.ejb.Schedule javax.ejb.Schedules jakarta.ejb.Schedule jakarta.ejb.Schedules，以便创建一个类型为 scheduled 的交易，表示已调度的任务执行

1.6.0，自 1.28.0 起支持 jakarta.ejb.Schedule

Quartz

1.0+

代理会检测实现 org.quartz.Job 的任何类的 execute 方法，以及扩展 org.springframework.scheduling.quartz.QuartzJobBean 的任何类的 executeInternal 方法，并创建一个类型为 scheduled 的交易，表示作业执行

注意：只有来自 quartz-jobs 依赖项的类才会被自动检测。对于其他作业的检测，必须将包添加到 application_packages 参数中。

1.8.0 - 2.0+

1.26.0 - 1.0+

TimerTask

代理会检测在 application_packages 中配置的包中扩展 java.util.TimerTask 的任何类的 run 方法，并创建一个类型为 scheduled 的交易，表示作业执行

1.18.0

日志框架编辑

代理中有多个与日志相关的功能，它们的支持取决于日志框架

关联：代理会自动将 trace.id、transaction.id 和 error.id 注入 MDC 实现（有关使用的框架特定 MDC 实现，请参见下文。MDC = 映射诊断上下文，一种使用附加信息丰富日志消息的标准方法）。对于服务关联，代理使用 ECS 日志格式设置 service.name、service.version 和 service.environment 的值（需要 ecs-logging-java 或重新格式化）。
错误捕获：自动捕获对 logger.error("message", exception) 等调用的异常。
重新格式化：启用 log_ecs_reformatting 后，日志将自动重新格式化为与 ECS 兼容的格式。

框架	支持的版本	描述	自
slf4j	1.4.1+		错误捕获 - 1.10.0
log4j2	关联 - 2.0+ 重新格式化 - 2.6+	`org.apache.logging.log4j.ThreadContext` 用于关联。	关联（跟踪） - 1.13.0 关联（服务） - 1.29.0 错误捕获 - 1.10.0 重新格式化 - 1.22.0
log4j1	关联和错误捕获 - 1.x 重新格式化 - 1.2.17	`org.apache.log4j.MDC` 用于关联。	关联（跟踪） - 1.13.0 关联（服务） - 1.38.0 重新格式化 - 1.22.0 错误捕获 - 1.30.0
Logback	1.1.0+	`org.slf4j.MDC` 用于关联。	关联（跟踪） - 1.0.0 关联（服务） - 1.38.0 ECS 重新格式化 - 1.22.0
JBoss 日志	3.0.0+	`org.jboss.logging.MDC` 用于关联。	关联（跟踪）- 1.23.0（LogManager 1.30.0）关联（服务） - 1.38.0 重新格式化 - 1.31.0
JUL - `java.util.logging`	所有受支持的 Java 版本	仅 ECS 日志记录（库或重新格式化）支持关联，因为 JUL 不提供任何 MDC 实现。	关联（跟踪）- 1.35.0（需要 ECS 日志记录）关联（服务）- 1.38.0（需要 ECS 日志记录）重新格式化 - 1.31.0 错误捕获 - 1.31.0
Tomcat JULI	7.0.0+	仅 ECS 日志记录（库或重新格式化）支持跟踪关联，因为 JUL 不提供任何 MDC 实现。不支持 Tomcat 访问日志。	关联（跟踪）- 1.35.0（需要 ECS 日志记录）关联（服务）- 1.38.0（需要 ECS 日志记录）重新格式化 - 1.35.0 错误捕获 - 1.35.0

进程框架编辑

框架	支持的版本	描述	自
`java.lang.Process`		检测 `java.lang.Process` 执行。尚不支持使用 `ProcessHandler` 的 Java 9 API。	1.13.0
Apache commons-exec	1.3	通过 `org.apache.commons.exec.DefaultExecutor` 和子类检测支持异步进程。	1.13.0

RPC 框架编辑

框架	支持的版本	描述	自
gRPC	1.6.1+	客户端（同步和异步）和服务器检测。当前未检测流调用。	1.16.0

AWS Lambda 运行时编辑

AWS Lambda 提供多个 JVM 基础镜像。开箱即用仅支持那些支持 AWS_LAMBDA_EXEC_WRAPPER 环境变量的镜像。

仍然可以使用不受支持的镜像运行，但需要通过环境变量显式提供代理配置。

标签	Java 运行时	操作系统	支持
11	Java 11 (Corretto)	Amazon Linux 2	是
8.al2	Java 8 (Corretto)	Amazon Linux 2	是
8	Java 8 (OpenJDK)	Amazon Linux 2018.03	否

Java 方法监控编辑

如果您在跨度时间线中看到空白并希望包含其他方法，则有多种选择。有关更多信息，请参阅 如何查找慢方法。

指标编辑

框架	描述	自
内置指标	代理发送各种系统、JVM 和应用程序指标。请参阅指标文档。	1.3.0
JMX	设置配置选项 `capture_jmx_metrics` 以监控任何 JMX 指标。	1.11.0
Micrometer	自动检测并报告每个 `MeterRegistry` 的指标。有关更多详细信息，请参阅Micrometer 指标。	1.18.0

注意事项编辑

尚未测试其他 JVM 语言，例如 Scala、Kotlin 和 Groovy。

« 监控 AWS Lambda Java 函数配置 »