« 使用 -javaagent 标记进行手动设置 程序化 API 设置以进行自连接 »
Elastic 文档 › ›设置代理

使用 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 Central 下载连接程序：Maven Central

在 1.22.0 之前的版本中，您需要下载 apm-agent-attach 工件的 standalone jar。

用法

编辑

将 Elastic APM Java 代理附加到与 --include-* / --exclude-* 发现规则匹配的所有正在运行的 JVM。

对于每个正在运行的 JVM，发现规则将按照提供的顺序进行评估。与当前评估的 Java 应用程序匹配的第一个规则确定结果。

  • 如果第一个匹配项是排除规则，则不会附加代理。
  • 如果第一个匹配项是包含规则，则将附加代理。
  • 如果没有规则匹配，则不会附加代理。

示例：以下命令将代理附加到所有主类包含 MyApplication 或从名为 my-application.jar 的 jar 文件启动或已设置系统属性 -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

如果提供，则此程序会持续运行并附加到所有运行和启动的 JVM，这些 JVM 与 --exclude 和 --include 过滤器匹配。

--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 文件的路径作为参数，并返回一个用于在附加的 JVM 上配置代理（agentmain 的 agentArguments）的 arg 字符串。当从该程序返回非零状态代码时，代理将不会附加到启动的 JVM。

参数的语法为 key1=value1;key2=value1,value2。有关所有可用的配置选项，请参阅 配置。

此选项不能与 --pid 和 --config 结合使用

-g, --log-level <off|fatal|error|warn|info|debug|trace|all>

设置日志级别。日志以 ECS JSON 格式发送到标准输出。

--log-file <file>

要记录到文件而不是控制台，请指定此程序应记录到的文件的路径。文件达到 10MB 大小时，日志文件会滚动。将保留一个历史文件，名称为 ${logFile}.1。

--agent-jar <file>

而不是捆绑的代理 jar，将提供的代理附加到目标 JVM。

--download-agent-version <agent-version>

而不是捆绑的代理 jar，从 Maven Central 下载并附加指定的代理版本。<agent-version> 可以是显式版本（例如：1.15.0）或 latest。代理根据已发布的 PGP 签名进行身份验证和验证。此选项需要互联网访问。

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 结尾的工件。

« 使用 -javaagent 标记进行手动设置 程序化 API 设置以进行自连接 »