Elastic APM Java Agent 配置不生效、命令行及日志问题咨询

当前环境与故障背景 #

• 部署拓扑：Elasticsearch、Kibana、APM Server部署在同一台EC2服务器，Jenkins应用所在服务器单独安装Elastic APM Java独立attach代理
• 代理状态：已成功attach到Jenkins进程，但动态配置无法正常生效
• 代理工作目录文件清单：

  apm-agent-attach-standalone.jar  elasticapm.properties
  

• 原有elasticapm.properties配置内容：

  service_name="jenkins-dev"
  server_url="http://x.x.x.x:8200"
  recording=true
  enabled=true
  log_level="DEBUG"
  log_file=_AGENT_HOME_/logs/elastic-apm.log
  

• 历史执行的attach命令：
  1. 首次执行命令，未加载同目录配置文件：
     sudo java -jar apm-agent-attach-standalone.jar --include '.*jenkins.*'
  2. 尝试传入启停配置：
     sudo java -jar apm-agent-attach-standalone.jar --include '.*jenkins.*' --config recording=false,enabled=false
  3. 尝试传入配置文件路径与日志路径：
     sudo java -jar apm-agent-attach-standalone.jar --include '.*jenkins.*' --config config_file=elasticapm.properties log_file=/etc/apmagents/apm.log
• 代理运行时错误日志：

  2021-04-12 10:47:20,338 [elastic-apm-server-reporter] ERROR co.elastic.apm.agent.report.IntakeV2ReportingEventHandler - Error trying to connect to APM Server. Some details about SSL configurations corresponding the current connection are logged at INFO level.
  2021-04-12 10:47:20,339 [elastic-apm-server-reporter] ERROR co.elastic.apm.agent.report.IntakeV2ReportingEventHandler - Failed to handle event of type JSON_WRITER with this error: Connection refused (Connection refused)
  2021-04-12 10:47:20,339 [elastic-apm-server-reporter] INFO  co.elastic.apm.agent.report.IntakeV2ReportingEventHandler - Backing off for 36 seconds (+/-10%)
  2021-04-12 10:47:24,345 [elastic-apm-remote-config-poller] ERROR co.elastic.apm.agent.configuration.ApmServerConfigurationSource - Connection refused (Connection refused)
  

核心问题解答 #

1. 命令行传入Elastic APM Java代理配置的正确方式 #

• 参数解析规则：--config参数支持连续传入多组键值对，多组配置必须使用英文逗号分隔，禁止用空格分隔。之前命令中多组配置用空格分隔的写法，代理只会识别第一个键值对，后续参数会被判定为无效参数，无法正常加载。
• 正确命令格式示例：

sudo java -jar apm-agent-attach-standalone.jar --include '.*jenkins.*' --config recording=false,enabled=false,config_file=/绝对路径/elasticapm.properties,log_file=/etc/apmagents/apm.log

• 关键注意事项：
• 传入config_file参数时，必须填写配置文件的绝对路径，写相对路径会导致代理无法定位配置文件
• 配置优先级：命令行传入的配置 > 配置文件内的配置 > 代理内置默认配置
• 使用sudo执行attach命令时，需确保所有配置文件、日志文件路径对进程运行用户可读，避免权限不足导致加载失败
• 配置文件内的键值对不要给值添加多余的双引号，properties格式解析时会把双引号作为值的一部分，导致配置值不符合预期（比如server_url会被解析为带前后引号的字符串，无法正常建立连接）
• 当前连接报错的本质原因：因为server_url配置没有被正确加载，代理默认尝试连接Jenkins本地的8200端口，本地无对应服务监听才会报Connection refused错误。需先确认Jenkins服务器到APM Server的网络通路无安全组拦截，再验证配置加载是否正常。
• 动态配置失效的关联原因：代理需要正常连接APM Server才能拉取远程动态配置，当前连接不通的状态下，动态配置自然无法生效。

2. log_file参数配置相关说明 #

• 不需要手动提前创建日志文件：代理启动时会自动创建指定路径的日志文件，如果父目录不存在，代理会自动逐层创建对应目录
• 日志污染应用日志的常见诱因：

1. log_file参数没有被正确加载，代理默认将日志输出到目标应用的标准输出/标准错误流，就会混在Jenkins本身的日志文件中
2. 日志路径的写入权限不足：如果指定的日志路径目录对Jenkins进程运行的用户无写入权限，代理会自动降级输出到应用日志

• 调整建议：确保指定的日志文件路径（比如/etc/apmagents/）的属主与Jenkins运行用户一致，避免权限问题导致日志无法写入独立文件。

内容的提问来源于stack exchange，提问作者kc7