故障排除

某些东西没有按预期工作？以下是一些找出问题所在的方法。

第一步，请检查您的堆栈是否与当前支持的技术兼容。

如果您无法找出问题所在，请在APM 讨论论坛中创建一个主题，我们会帮助您解决问题。

更新到最新代理版本编辑

代理会经常更新，并且版本发布与堆栈中的其他组件没有强绑定关系。

因此，尝试更新到最新发布的代理版本通常是推荐的第一步故障排除步骤。如果可能，尝试使用最新快照甚至更好，因为它将包含尚未发布的修复程序。

有关更多详细信息，请参阅升级文档。

与其他代理一起运行编辑

与许多其他 Java 代理一样，我们的代理通过在运行时将字节码注入类来对类进行检测。我们的字节码检测保证只生成有效的字节码，并且永远不会更改类的“模式”。如果您除了我们之外还使用其他具有相同保证的 Java 代理，它们不应该相互干扰。但是，一些 Java 代理不符合这些保证，在这种情况下，可能存在与我们并行使用它们的问题。如果您遇到错误，首先要做的事情之一是删除任何其他代理，以检查这是否确实是代理不匹配的情况。我们仍然可以找到一种方法让它们一起工作，但此信息对于我们提供帮助至关重要，因此请确保在报告此类问题时包含它。

日志记录编辑

有几个与日志记录相关的配置选项。其中最重要的一个是log_level。

将日志级别设置为DEBUG甚至TRACE以获取有关代理行为的更多信息。

在寻求帮助时，请始终发布日志文件的全部内容。使用过程以确保在报告潜在问题时日志一致。

当代理启动时，您应该看到类似于这些的日志

[main] INFO co.elastic.apm.agent.configuration.StartupInfo - Starting Elastic APM (unknown version) on Java 10 (Oracle Corporation) Mac OS X 10.13.6
[apm-server-healthcheck] INFO co.elastic.apm.agent.report.ApmServerHealthChecker - Elastic APM server is available: {"build_date":"2018-11-05T07:58:08Z","build_sha":"dffb98a72a262ca22adad0152f0245ea743ea904","version":"7.0.0-alpha1"}
[main] DEBUG co.elastic.apm.agent.configuration.StartupInfo - service_name: 'elastic-apm-test' (source: Java System Properties)
[main] DEBUG co.elastic.apm.agent.configuration.StartupInfo - log_level: 'DEBUG' (source: Java System Properties)

确保在发布日志文件之前执行一些对应用程序的请求。每个请求至少应在日志中添加一些类似于这些的行

[http-nio-8080-exec-10] DEBUG co.elastic.apm.agent.impl.ElasticApmTracer - startTransaction '' 00-2a82cbe3df7a0208f7be6da65be260d1-05e72d045206587a-01 {
[http-nio-8080-exec-10] DEBUG co.elastic.apm.agent.impl.ElasticApmTracer - Activating '' 00-2a82cbe3df7a0208f7be6da65be260d1-05e72d045206587a-01 on thread 66
[http-nio-8080-exec-10] DEBUG co.elastic.apm.agent.impl.transaction.Span - startSpan '' 00-2a82cbe3df7a0208f7be6da65be260d1-b2ffa0401105e3d8-01 {
[http-nio-8080-exec-10] DEBUG co.elastic.apm.agent.impl.ElasticApmTracer - Activating 'APIRestController#products' 00-2a82cbe3df7a0208f7be6da65be260d1-b2ffa0401105e3d8-01 on thread 66
[http-nio-8080-exec-10] DEBUG co.elastic.apm.agent.impl.transaction.Span - startSpan '' 00-2a82cbe3df7a0208f7be6da65be260d1-49b9d805eca42ec6-01 {
[http-nio-8080-exec-10] DEBUG co.elastic.apm.agent.impl.ElasticApmTracer - Activating '' 00-2a82cbe3df7a0208f7be6da65be260d1-49b9d805eca42ec6-01 on thread 66
[http-nio-8080-exec-10] DEBUG co.elastic.apm.agent.impl.ElasticApmTracer - Deactivating 'SELECT' 00-2a82cbe3df7a0208f7be6da65be260d1-49b9d805eca42ec6-01 on thread 66
[http-nio-8080-exec-10] DEBUG co.elastic.apm.agent.impl.transaction.Span - endSpan 'SELECT' 00-2a82cbe3df7a0208f7be6da65be260d1-49b9d805eca42ec6-01
[apm-reporter] DEBUG co.elastic.apm.agent.report.IntakeV2ReportingEventHandler - Receiving SPAN event (sequence 23)
[apm-reporter] DEBUG co.elastic.apm.agent.report.IntakeV2ReportingEventHandler - Starting new request to http://127.0.0.1:8200/intake/v2/events
[http-nio-8080-exec-10] DEBUG co.elastic.apm.agent.impl.ElasticApmTracer - Deactivating 'APIRestController#products' 00-2a82cbe3df7a0208f7be6da65be260d1-b2ffa0401105e3d8-01 on thread 66
[http-nio-8080-exec-10] DEBUG co.elastic.apm.agent.impl.transaction.Span - endSpan 'APIRestController#products' 00-2a82cbe3df7a0208f7be6da65be260d1-b2ffa0401105e3d8-01
[apm-reporter] DEBUG co.elastic.apm.agent.report.IntakeV2ReportingEventHandler - Scheduling request timeout in 10s
[apm-reporter] DEBUG co.elastic.apm.agent.report.IntakeV2ReportingEventHandler - Receiving SPAN event (sequence 24)
[http-nio-8080-exec-10] DEBUG co.elastic.apm.agent.impl.ElasticApmTracer - Deactivating 'APIRestController#products' 00-2a82cbe3df7a0208f7be6da65be260d1-05e72d045206587a-01 on thread 66
[http-nio-8080-exec-10] DEBUG co.elastic.apm.agent.impl.ElasticApmTracer - endTransaction 'APIRestController#products' 00-2a82cbe3df7a0208f7be6da65be260d1-05e72d045206587a-01
[apm-reporter] DEBUG co.elastic.apm.agent.report.IntakeV2ReportingEventHandler - Receiving TRANSACTION event (sequence 25)

如果您在日志中没有看到任何内容，那么您正在使用的技术堆栈可能不受支持。

之后，您应该看到日志表明代理已成功将数据发送到 APM 服务器

[apm-request-timeout-timer] DEBUG co.elastic.apm.agent.report.IntakeV2ReportingEventHandler - Request flush because the request timeout occurred
[apm-reporter] DEBUG co.elastic.apm.agent.report.IntakeV2ReportingEventHandler - Receiving FLUSH event (sequence 26)
[apm-reporter] DEBUG co.elastic.apm.agent.report.IntakeV2ReportingEventHandler - Flushing 10912 uncompressed 2667 compressed bytes

如果 APM 服务器响应 400，则可能表示 JSON 验证错误。然后日志将包含无法验证的实际文档

[apm-reporter] INFO co.elastic.apm.agent.report.IntakeV2ReportingEventHandler - Backing off for 0 seconds (±10%)
[apm-reporter] WARN co.elastic.apm.agent.report.IntakeV2ReportingEventHandler - Server returned HTTP response code: 400 for URL: http://127.0.0.1:8200/intake/v2/events
[apm-reporter] WARN co.elastic.apm.agent.report.IntakeV2ReportingEventHandler - {"accepted":13,"errors":[{"message":"Problem validating JSON document against schema: I[#] S[#] doesn't validate with \"span#\"\n  I[#] S[#/allOf/2] allOf failed\n    I[#] S[#/allOf/2/required] missing properties: \"transaction_id\"","document":"{\"span\":{\"name\":\"OpenTracing product span\",\"timestamp\":29352159207,\"id\":\"aeaa7e0ac95acad6\",\"trace_id\":\"d88b5cbfc4536f9a700cd114a53bfeae\",\"parent_id\":\"082fd71ce7e4089a\",\"duration\":17.992,\"context\":{\"tags\":{\"productId\":\"1\"}},\"type\":\"unknown\"}}"}]}

捕获日志过程编辑

理想情况下，这应该在生产环境之外完成。

大多数调查都需要使用DEBUG日志级别，因此请使用DEBUG，除非要求使用TRACE。

在这里，我们将代理日志文件称为/tmp/agent.log，但可以使用任何其他位置。

代理匹配启发式方法编辑

代理依赖于启发式方法来有效地定义哪些类需要进行检测或不进行检测，以防止检测开销。

这些启发式方法基于包和类名，并受application_packages和jms_listener_packages配置的影响。但是，如果检测没有按预期应用，或者您想在没有正确了解应用程序内部结构的情况下调查创建配置，那么禁用这些启发式方法以进行调查可能相关

调试编辑

有时，仅仅阅读日志不足以调试问题。由于代理是开源的并在 Maven Central 上发布，因此调试代理代码非常容易。

为了让您的 IDE 下载源代码，首先声明对代理的依赖关系。

pom.xml。

<dependency>
    <groupId>co.elastic.apm</groupId>
    <artifactId>apm-agent</artifactId>
    <version>${elastic-apm.version}</version>
    <scope>provided</scope>
</dependency>

build.gradle。

compileOnly "co.elastic.apm:apm-agent:$elasticApmVersion"

常见问题编辑

Kibana APM 应用程序中没有数据编辑

此问题的最常见来源是代理和 APM 服务器之间的连接问题。

如果 APM 服务器没有从代理接收数据，请检查代理是否能够建立与服务器的连接。在代理日志中，请注意包含Elastic APM server is available和Elastic APM server is not available的日志。

如果您看到消息Elastic APM server is not available，则代理在连接到 APM 服务器时遇到问题。检查server_url的设置，并确保代理能够连接到服务器。尝试从代理运行的机器上执行curl -v <apm-server-url>。服务器应该以 200 状态代码响应。

如果 APM 服务器没有成功响应，请查看 APM 服务器日志以验证服务器是否确实正在运行。还要确保配置您的防火墙，以便代理运行的主机可以打开到 APM 服务器的 HTTP 连接。

Kibana APM 应用程序显示“未知路由”编辑

默认情况下，事务使用处理请求的 Servlet 名称命名。因此，如果请求未到达 Servlet，代理将默认将事务命名为“未知路由”。

这可能发生的原因有两个：

如果建议的修复程序无法解决问题，或者需要自定义名称，则可以在整个请求处理流程中使用我们的 API 手动设置事务名称。

针对旧版 Java 版本编译的库编辑

如果您在应用程序中看到类似以下的警告，则表示您正在使用针对非常旧的 Java 版本编译的库。

org.apache.commons.dbcp.DelegatingStatement uses an unsupported class file version (pre Java 5) and can't be instrumented.
Consider updating to a newer version of that library.

这主要涉及 JDBC 驱动程序。将它们更新到更新的版本应该可以解决问题。

无法找到 Premain-Class 清单属性编辑

如果您使用的是针对应用程序服务器的-javaagent标志的手动设置，并且看到Failed to find Premain-Class manifest attribute错误以及启动失败，那么您可能指向了错误的 jar 文件。

要指向的正确 jar 文件应采用elastic-apm-agent-<version>.jar的形式，有关如何下载此文件的更多信息，请参阅手动设置说明。

与 APM 服务器通信编辑

unable to find valid certification path to requested target - 服务器身份验证失败。查看APM 服务器证书身份验证。

java.net.SocketException: Broken pipe - 其中一个选项是客户端身份验证失败。查看代理证书身份验证。

对于其他与 SSL/TLS 相关的問題，请查看JSSE 疑难解答部分。您可以将-Djavax.net.debug=all添加到 JVM 命令行以获取有关问题的更多详细信息。

不常见的问题编辑

JVM 崩溃编辑

通常，JVM 崩溃表明 JVM 错误是由在跟踪应用程序及其依赖项的特定配置中安装 Java 代理而引发的。因此，首先要尝试的是将 JVM 升级到最新的次要版本。

已知问题

每当您遇到 JVM 崩溃时，请通过我们的论坛或通过在我们的GitHub 存储库上打开问题来报告。查找崩溃日志（例如，hs_err_pid<PID>.log）并在报告时提供它，以及描述您的设置和场景的所有因素。

JVM 挂起编辑

如果您的 JVM 在附加 Java 代理时挂起，请创建线程转储（例如，通过jstack）并通过我们的论坛或通过在我们的GitHub 存储库上打开问题来报告。

使用jlink的自定义 Java 运行时编辑

如果您使用jlink创建自定义运行时，请确保添加以下模块：--add-modules java.base,java.logging,java,jdk.zipfs,java.management,jdk.management

禁用代理编辑

如果代理对生产应用程序造成干扰，则可以在进行故障排除时禁用代理。

使用动态配置，您可以通过将recording设置为false来禁用事件的记录。

如果这不起作用，您可以通过将enabled设置为false来完全禁用代理。您需要重新启动应用程序才能使此更改生效。

不受支持的框架版本编辑