故障排除

某些功能无法按预期工作？以下是一些找出问题所在的方法。

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

如果您无法找出问题所在，请不要担心。在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.SpanImpl - 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.SpanImpl - 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.SpanImpl - 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.SpanImpl - 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日志级别，因此除非要求使用TRACE，否则请使用DEBUG。

在这里，我们将代理日志文件称为/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"

此问题的最常见原因是代理和 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 连接。

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

这可能发生的原因有两个

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

如果您的应用程序中出现类似这样的警告，则表示您正在使用针对非常旧的 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 驱动程序。将它们更新到较新的版本应该可以解决问题。

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

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

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 中的错误是由在被跟踪应用程序及其依赖项的特定配置中安装 Java 代理而导致的。因此，首先尝试将 JVM 升级到最新的次要版本。

已知问题

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

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

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

如果代理意外导致生产应用程序中断，您可以在进行故障排除时禁用代理。

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

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