更新时间:2025-09-28 GMT+08:00
分享

为Docker应用安装Agent

前提条件

  • 部署APM Agent时,必须确保接入APM的机器与APM服务网络连通,Agent才能正常工作。可使用“curl -kv”命令测试目标机器与APM服务器网络是否连通。例如,以检查华北-北京四区域,且接入方式选择“增强型探针”的连通性为例,请登录应用所部署的机器,并输入命令curl -kv 100.125.12.108:41333,其他区域地址请参考探针接入地址
  • Java语言支持增强型探针、OpenTelemetry和Skywalking。

操作步骤

  1. 登录APM控制台
  2. 单击左侧,选择“管理与监管 > 应用性能管理 APM”,进入APM服务页面。
  3. 在左侧导航栏中选择“应用监控 > 应用列表”。
  4. 单击“接入应用”,进入接入应用页面。

    图1 接入应用

  5. 选择“区域”和“应用”。单击“创建应用”,弹出“创建应用”弹窗,可以具体操作参见创建应用

    图2 基础信息

  6. “接入方式”选择增强型探针、OpenTelemetry或者Skywalking。
  7. “服务端语言”选择Java。

    图3 接入方式

  8. 使用PuTTY等远程登录工具,登录待安装Agent的Linux操作系统主机,并以root权限执行相关命令。
  9. 根据应用类型选择接入对应的接入方式,按照步骤接入。

    • 增强型探针
      • 虚机接入
        1. 请到“系统管理 > 访问密钥”界面,获取JavaAgent所需的AK、SK。获取“访问密钥”的方法,请参见访问密钥
        2. 使用PuTTY等远程登录工具,登录待安装Agent的Linux操作系统主机,并以root或service权限执行相关命令。执行安装命令的用户需要和启动应用的用户保持一致。
        3. 执行如下命令,下载并安装JavaAgent。
          curl -k https://javaagent.obs.****.com/apm_agent_install2.sh -o apm_agent_install.sh && bash apm_agent_install.sh -ak {APM_AK} -sk {APM_SK} -masteraddress https://**.**.**.**:**** -obsaddress https://javaagent.obs..****.com -version latest; history -cw; history -r
          表1 虚机接入参数说明

          参数

          说明

          是否必填

          APM_AK

          APM_SK

          安装JavaAgent的AK和SK。获取APM_AK和APM_SK方法参见访问密钥

          如果直接复制命安装JavaAgent的命令,请注意填写“APM_AK”和“APM_SK”时,删除“{}”。

          例如:

          curl -k https://javaagent.***/apm_agent_install2.sh -o apm_agent_install.sh && bash apm_agent_install.sh -ak * -sk * -masteraddress https://**** -obsaddress https://javaagent.***.com -version latest; history -cw; history -r 

          必填

          masteraddress

          接入地址,请参见探针接入地址

          必填

          version

          Agent版本号。APM提供的latest探针版本,能同时支持多个jdk环境。

          必填

          探针安装路径

          Agent探针安装的路径。

          必填

          组件名称

          组件名称,代表一个组件,需要使用英文字符开头。同一个应用下,组件名称不能重复。一个组件可以包含多个环境。不能重复,如果要重复,使用instanceName区分。

          必填

          环境名称

          环境名称,代表一个应用在一个地方的部署。一个应用程序根据配置不同可以部署多个环境,比如测试环境,现网环境。每个环境都在一个region部署,具有唯一的region属性。该参数可以为空,代表默认环境。

          选填

          环境标签

          环境标签,主要用于环境过滤,多个环境打上相同的环境标签,在web页面上可以通过标签将这些环境过滤出来。该参数可以为空。

          选填

          应用名称

          应用英文名称,为全局概念。如果填写,则必须提前创建该应用。如果为空,则代表默认应用(开通APM时系统会自动创建一个默认应用)。

          选填

          子应用名称

          子应用,为全局概念,在应用下面子文件夹。该参数可以为空,为空代表资源挂载在根应用下面,子应用最多支持三层。比如 a/b/c,a、b、c各代表一层。

          选填

          用户应用

          用户应用jar包名称。

          必填

        4. 添加启动命令并重启应用。Agent安装大约需要1分钟。安装完毕后,在应用服务器的启动脚本中添加以下JVM参数,然后重新启动您的应用。启动命令格式如下。
          java -javaagent:探针安装路径/apm-javaagent/apm-javaagent.jar=appName=组件名称,env=环境名称,envTag=环境标签,business=应用别名,subBusiness=子应用名称 -jar 用户应用.jar

          启动命令示例。

          java -javaagent:/root/my-dir/apm-javaagent/apm-javaagent.jar=appName=my-service,env=dev -jar test-2.0.0-SNAPSHOT.jar
          表2 启动命令参数说明

          参数

          说明

          是否必填

          探针安装路径

          Agent探针安装的路径。

          必填

          组件名称

          组件名称,代表一个组件,需要使用英文字符开头。同一个应用下,组件名称不能重复。一个组件可以包含多个环境。不能重复,如果要重复,使用instanceName区分。

          必填

          环境名称

          环境名称,代表一个应用在一个地方的部署。一个应用程序根据配置不同可以部署多个环境,比如测试环境,现网环境。每个环境都在一个region部署,具有唯一的region属性。该参数可以为空,代表默认环境。

          选填

          环境标签

          环境标签,主要用于环境过滤,多个环境打上相同的环境标签,在web页面上可以通过标签将这些环境过滤出来。该参数可以为空。

          选填

          应用英文名称

          应用英文名称,为全局概念。如果填写,则必须提前创建该应用。如果为空,则代表默认应用(开通APM时系统会自动创建一个默认应用)。

          选填

          子应用

          子应用,为全局概念,在应用下面子文件夹。该参数可以为空,为空代表资源挂载在根应用下面,子应用最多支持三层。比如 a/b/c,a、b、c各代表一层。

          选填

          用户应用

          用户所属的应用名称。

          必填

      • CCE接入
        1. 前提条件。
          • CCE容器安装Agent建议使用自有探针。
          • 已经使用CCE部署了容器应用。
        2. 请到“系统管理 > 访问密钥”界面,获取JavaAgent所需的AK、SK。获取“访问密钥”的方法,请参见访问密钥
        3. 目前只支持部署CCE的Java应用。相关参数说明参见表3
          表3 性能管理配置参数列表

          参数名称

          参数说明

          安装探针

          选择安装探针。目前支持“不启动”和“APM 2.0探针”。

          探针版本

          选择探针的版本类型。探针类型建议与负载所在node节点的CPU架构对应版本一致。

          APM提供的latest探针版本,能同时支持多个jdk环境。

          探针升级策略

          探针升级的方式、策略。默认为“重启自动升级”。

          • 重启自动升级:每次都尝试重新下载镜像。
          • 重启手动升级:如果本地有该镜像,则使用本地镜像,本地不存在时下载镜像。

          APM环境

          输入APM环境名称,该参数为选填。

          APM应用

          选择一个已有的APM应用。

          子应用

          输入APM子应用,该参数为选填。

          接入密钥

          将会自动获取APM服务的密钥信息,详情参见访问密钥

        4. 登录CCE控制台,将容器服务上的Java应用通过Pinpoint探针接入到APM。CCE接入方法参见CCE容器接入JavaAgent
    • OpenTelemetry
      数据接入,相关参数与操作步骤如下。
      表4 参数说明

      参数

      说明

      是否必填

      探针安装路径

      opentelemetry-agent-path,即:探针下载后存放的路径。

      必填

      应用名称

      应用显示的名称。一个应用代表一个逻辑单元,是一个全局概念,各个region都可以看到相同的应用信息,比如一个租户下面比较独立的功能模块可以定义为一个应用。

      必填

      组件名称

      组件名称,代表一个组件,需要使用英文字符开头。同一个应用下,组件名称不能重复。一个组件可以包含多个环境。不能重复,如果要重复,使用instanceName区分。

      必填

      环境名称

      环境名称,代表一个应用在一个地方的部署。一个应用程序根据配置不同可以部署多个环境,比如测试环境,现网环境。每个环境都在一个region部署,具有唯一的region属性。该参数可以为空,代表默认环境。

      选填

      子应用

      子应用,为全局概念,在应用下面子文件夹。该参数可以为空,为空代表资源挂载在根应用下面,子应用最多支持三层。比如 a/b/c,a、b、c各代表一层。

      选填

      用户应用

      用户所属的应用名称。

      必填

      1. 下载OpenTelemetry Java Agent。前往Agent下载地址,推荐下载1.x版本,下载后将Agent文件放在Java进程有访问权限的目录,例如:/root/my-dir。
      2. 使用PuTTY等远程登录工具,登录待安装Agent的Linux操作系统主机,并以root或service权限执行相关命令。执行安装命令的用户需要和启动应用的用户保持一致。
      3. 添加启动命令并重启应用,命令格式如下。
        java -javaagent:opentelemetry-agent-path -Dotel.exporter.otlp.traces.endpoint=http://**.**.**.**:*** -Dotel.exporter.otlp.headers=Authentication=****** -Dotel.service.name=应用名称.组件名称.环境名称 -Dotel.metrics.exporter=none -jar 用户应用.jar
        启动命令示例。
        java -javaagent:/root/my-dir/opentelemetry-javaagent.jar -Dotel.exporter.otlp.traces.endpoint=http://**.**.**.**:*** -Dotel.exporter.otlp.headers=Authentication=****** -Dotel.service.name=default.my-service.dev -Dotel.metrics.exporter=none -jar myApp.jar
    • Skywalking
      数据接入,相关参数与操作步骤如下。
      表5 参数说明

      参数

      说明

      是否必填

      探针安装路径

      skywalking-agent-path,即:探针下载后存放的路径。

      必填

      应用名称

      应用显示的名称。一个应用代表一个逻辑单元,是一个全局概念,各个region都可以看到相同的应用信息,比如一个租户下面比较独立的功能模块可以定义为一个应用。

      必填

      组件名称

      组件名称,代表一个组件,需要使用英文字符开头。同一个应用下,组件名称不能重复。一个组件可以包含多个环境。不能重复,如果要重复,使用instanceName区分。

      必填

      环境名称

      环境名称,代表一个应用在一个地方的部署。一个应用程序根据配置不同可以部署多个环境,比如测试环境,现网环境。每个环境都在一个region部署,具有唯一的region属性。该参数可以为空,代表默认环境。

      选填

      子应用

      子应用,为全局概念,在应用下面子文件夹。该参数可以为空,为空代表资源挂载在根应用下面,子应用最多支持三层。比如 a/b/c,a、b、c各代表一层。

      选填

      用户应用

      用户所属的应用名称。

      必填

      1. 下载skywalking。前往skywalking官网,推荐下载 Java Agent 8.9.0 及以上版本,解压后 Agent 文件放至在 Java 进程有访问权限的目录。如需配置插件,在启动阶段将新的插件放进/plugins目录中,即可令插件生效。将插件从该目录删除,即可令其失效。日志文件默认输出到/logs目录中。
      2. 添加启动命令并重启应用。
        1. 接入 Agent 配置相关参数,有如下两种配置方式。
          • 在应用程序的启动命令行中配置。
            java -javaagent:skywalking-agent-path -Dskywalking.collector.backend_service=100.79.29.107:11800 -Dskywalking.agent.authentication=***** -Dskywalking.agent.service_name=应用名称.组件名称.环境名称 -jar <yourApp>.jar
          • 在 agent/config/agent.config 中配置。
            collector.backend_service=100.79.29.107:11800
            agent.authentication=******
            agent.service_name=应用名称.组件名称.环境名称
        2. 配置 javaagent 路径,并重新启动应用。
          java -javaagent:skywalking-agent-path -jar yourApp.jar 

          注意:如果您两种方式均进行配置,则只在启动命令行中的配置生效。

          启动命令示例:

          java -javaagent:/root/my-dir/opentelemetry-javaagent.jar -Dskywalking.collector.backend_service=100.79.29.107:11800 -Dskywalking.agent.authentication=***** -Dskywalking.agent.service_name=<default.my-service.dev> -jar myApp.jar

  10. 将复制的命令放入Dockerfile文件中,并增加JAVA_TOOL_OPTIONS环境变量。

    RUN curl -k https://javaagent.obs.xx-xxx-x.xxxx.huawei.com/apm_agent_install2.sh -o apm_agent_install.sh && bash apm_agent_install.sh -ak {AK}-sk {SK} -masteraddress https://xxx.xx.xx.xx:xxx -obsaddress https://javaagent.obs.xx-xxx-x.xxxx.huawei.com -version latest
    
    ENV JAVA_TOOL_OPTIONS=-javaagent:${PROJECT_DIR}/apm-javaagent/apm-javaagent.jar=appName=${APP_NAME}

  11. 重新构建镜像,Dockerfile文件示例。

    FROM openjdk
    RUN mkdir /opt/cloud 
    ENV PROJECT_DIR=/opt/cloud
    ENV APP_NAME=hello
    WORKDIR $PROJECT_DIR
    ADD ${APP_NAME}.jar ${APP_NAME}.jar
    RUN curl -k https://javaagent.obs.xx-xxx-x.xxxx.huawei.com/apm_agent_install2.sh -o apm_agent_install.sh && bash apm_agent_install.sh -ak {AK}-sk {SK} -masteraddress https://xxx.xx.xx.xx:xxx -obsaddress https://javaagent.obs.xx-xxx-x.xxxx.huawei.com -version latest
    ENV JAVA_TOOL_OPTIONS=-javaagent:${PROJECT_DIR}/apm-javaagent/apm-javaagent.jar=appName=${APP_NAME}
    CMD ["bash","-c","java -jar ${APP_NAME}.jar" ]

  12. 重新部署应用。

相关文档