使用 apm-agent-attach-cli.jar 自动设置
编辑使用 apm-agent-attach-cli.jar 自动设置编辑
apm-agent-attach-cli.jar 是一个可执行的 Java 命令行程序，它将 Elastic APM Java 代理附加到特定的 JVM 或其运行所在的同一主机的所有 JVM，它具有以下属性
- 无需更改应用程序代码。
- 不需要更改 JVM 参数，也不需要更改应用程序服务器配置。
- 允许检测给定主机上的所有 JVM，包括正在运行的 JVM 和通过监控启动的新 JVM。
- 需要在主机上复制并执行
apm-agent-attach-cli.jar二进制文件。 - 依赖于 JVM 的 Java 代理的运行时附加功能，但不需要完整的 JDK 或
tools.jar。 - 应用程序启动期间发生的事件可能不会被捕获。
- 通常不可能使用此机制附加到在容器或 Kubernetes Pod 中运行的 JVM。对于 Kubernetes，我们支持使用变异 webhook自动附加；对于 Docker，您可以尝试下面的脚本
支持的环境编辑
在 Unix 操作系统（如 Linux 和 macOS）上，支持附加到基于 HotSpot 的 JVM（如 OpenJDK 和 Oracle JDK）和 OpenJ9 JVM。运行附加程序的用户必须与运行目标 JVM 的用户相同，或者必须具有切换到该用户的权限。
在 Windows 上，仅支持基于 HotSpot 的 JVM。运行附加程序的用户必须与运行目标 JVM 的用户相同。
目标 VM 不必与启动附加程序的 VM 相同。这意味着可以使用 Java 7 运行附加程序，并将代理附加到在 Java 11 下运行的应用程序。但是，VM 的类型必须相同：不可能从基于 HotSpot 的 VM 附加到 J9 VM，反之亦然。
下载编辑
您可以从 Maven 中央存储库下载附加程序：Maven 中央存储库
在 1.22.0 之前的版本中，您必须下载 apm-agent-attach 工件的 standalone jar。
用法编辑
将 Elastic APM Java 代理附加到与 --include-* / --exclude-* 发现规则匹配的所有正在运行的 JVM。
对于每个正在运行的 JVM，发现规则将按照提供的顺序进行评估。与当前评估的 Java 应用程序匹配的第一条规则决定了结果。
- 如果第一个匹配项是排除规则，则不会附加代理。
- 如果第一个匹配项是包含规则，则将附加代理。
- 如果没有规则匹配，则不会附加代理。
示例：以下命令将代理附加到所有主类包含 MyApplication 的 JVM，或者从名为 my-application.jar 的 jar 文件启动的 JVM，或者设置了系统属性 -Delastic.apm.attach=true 的 JVM，除非 JVM 在 root 用户下运行。它还使附加程序持续运行，以便它将代理附加到与发现规则匹配的启动 JVM。此外，它还应用了一些配置选项。
java -jar apm-agent-attach-cli.jar \
--exclude-user root \
--include-main MyApplication my-application.jar \
--include-vmarg elastic.apm.attach=true \
--continuous \
--config service_name=my-cool-service \
--config server_url=http://127.0.0.1:8200
选项编辑
- -l, --list
-
这使您可以对包含/排除发现规则进行试运行。程序不会附加到匹配的 JVM，而是会打印与包含/排除发现规则匹配的 JVM。与
jps -l类似，输出包括 PID 以及主类名或 jar 文件的路径。 - -v, --list-vmargs
-
通过
--list列出正在运行的 JVM 时，包括传递给 JVM 的参数。提供类似于jps -lv的输出。JVM 参数可能包含敏感信息，例如通过系统属性提供的密码。
- -c, --continuous
-
如果提供，则此程序将持续运行，并附加到与
--exclude和--include过滤器匹配的所有正在运行和启动的 JVM。 - --no-fork [1.35.0] 在 1.35.0 中添加。
-
默认情况下，当用户 A 运行附加程序并且用户 B 运行目标进程时，附加程序将尝试以用户 B 的身份启动另一个进程。如果提供了此配置选项，则附加程序将不会分叉。相反，它将尝试以当前用户的身份直接附加。
- --include-all
-
包括所有要附加的 JVM。
- --include-pid <pid>…
-
要包含的 PID。
- --include-main/--exclude-main <pattern>…
-
应将 Java 代理附加到的应用程序的完全限定主类名或 JAR 路径的正则表达式。执行部分匹配，以便
foo匹配/bin/foo.jar。 - --include-vmarg/--exclude-vmarg <pattern>…
-
与传递给 JVM 的参数（例如系统属性）匹配的正则表达式。执行部分匹配，以便
attach=true匹配系统属性-Delastic.apm.attach=true。 - --include-user/--exclude-user <user>…
-
与运行 JVM 的操作系统用户匹配的用户名。对于包含的用户，请确保运行此程序的用户是同一用户，或者具有切换到运行目标 JVM 的用户的权限。
- -a, --args <agent_arguments>
-
已弃用，取而代之的是 --config。
如果设置，则参数用于在附加的 JVM 上配置代理（agentmain 的 agentArguments）。
参数的语法为
key1=value1;key2=value1,value2。有关所有可用的配置选项，请参阅配置。此选项不能与
--args-provider一起使用 - -C --config <key=value>…
-
此可重复选项设置一个代理配置选项。
示例：
--config server_url=http://127.0.0.1:8200 - -A, --args-provider <args_provider_script>
-
新 JVM 启动时调用的程序的名称。该程序获取 pid 以及主类名或 JAR 文件的路径作为参数，并返回一个 arg 字符串，该字符串用于在附加的 JVM 上配置代理（agentmain 的 agentArguments）。从此程序返回非零状态代码时，代理将不会附加到启动的 JVM。
参数的语法为
key1=value1;key2=value1,value2。有关所有可用的配置选项，请参阅配置。此选项不能与
--pid和--config一起使用 - -g, --log-level <off|fatal|error|warn|info|debug|trace|all>
-
设置日志级别。日志以 ECS JSON 格式发送到 stdout。
- --log-file <file>
-
要登录到文件而不是控制台，请指定此程序应登录到的文件的路径。日志文件在达到 10MB 的大小时会滚动更新。将保留一个历史文件，名称为
${logFile}.1。 - --agent-jar <file>
-
将提供的代理附加到目标 JVM，而不是捆绑的代理 jar。
- --download-agent-version <agent-version>
-
从 Maven 中央存储库下载并附加指定的代理版本，而不是捆绑的代理 jar。<agent-version> 可以是显式版本（例如：
1.15.0）或latest。代理根据发布的 PGP 签名进行身份验证和验证。此选项需要 Internet 访问。
Docker编辑
使用此脚本自动附加到主机上运行的所有 Docker 容器。此脚本不会返回，而是持续侦听启动的容器，它也会附加到这些容器。
此脚本是实验性的，可能不适用于所有容器。特别是 jq --raw-output .[0].Config.Cmd[0]) == java 可能会有所不同。
attach.sh.
#!/usr/bin/env bash
set -ex
attach () {
# only attempt attachment if this looks like a java container
if [[ $(docker inspect ${container_id} | jq --raw-output .[0].Config.Cmd[0]) == java ]]
then
echo attaching to $(docker ps --no-trunc | grep ${container_id})
docker cp ./apm-agent-attach-*-cli.jar ${container_id}:/apm-agent-attach-cli.jar
docker exec ${container_id} java -jar /apm-agent-attach-cli.jar --config
fi
}
# attach to running containers
for container_id in $(docker ps --quiet --no-trunc) ; do
attach
done
# listen for starting containers and attach to those
docker events --filter 'event=start' --format '{{.ID}}' |
while IFS= read -r container_id
do
attach
done
故障排除编辑
如果您收到类似 no main manifest attribute, in apm-agent-attach.jar 的消息，则表示您使用了错误的工件。请使用以 -cli.jar 结尾的工件。