›

支持的技术

编辑

支持的技术

编辑

Elastic APM Java Agent 自动检测各种 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 service refresh 5+ (build 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'.

如该消息所示，如果需要，您可以通过将 -Delastic.apm.disable_bootstrap_checks=true 添加到 JVM 参数或为 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 查询创建 DB 跨度。这包括由 Hibernate 等 O/R 映射器执行的 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（GA）
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（GA）

消息框架

编辑

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

框架	支持的版本	描述	自
JMS	1.1, 2.0	代理会将 JMS 发送和接收捕获为 Span/事务	`javax.jms`（自 1.13.0 版起），`jakarta.jms`（自 1.40.0 版起）
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、2.21+（自 1.44.0 版起）

分布式跟踪

编辑

消息系统客户端的 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 Server 和 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、`jakarta.ejb.Schedule`（自 1.28.0 版起）
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、jakarta.ejb.Schedule（自 1.28.0 版起）

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 = 映射诊断上下文，这是一种将日志消息与其他信息进行丰富以进行标准化的方法）。为了进行服务关联，代理会设置 service.name、service.version 和 service.environment 的值，需要使用 ECS 日志格式（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 Logging	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 版本	由于 JUL 未提供任何 MDC 实现，因此仅在使用 ECS 日志（库或重新格式化）时才支持关联。	关联（跟踪） - 1.35.0（需要 ECS 日志）关联（服务） - 1.38.0（需要 ECS 日志）重新格式化 - 1.31.0 错误捕获 - 1.31.0
Tomcat JULI	7.0.0+	由于 JUL 未提供任何 MDC 实现，因此仅在使用 ECS 日志（库或重新格式化）时才支持跟踪关联。不支持 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 函数配置 »