文档首页/ 应用平台 AppStage/ AppStage用户指南（运维中心）/ 基于调用链服务进行链路追踪诊断/ 接入NUWA Trace Agent
更新时间：2025-06-27 GMT+08:00
查看PDF
分享

接入NUWA Trace Agent

使用javaagent方式接入NUWA Trace Agent，采集调用链类数据及指标类数据，数据保留期为7天，并按小时和天级进行聚合存储到MPPDB中，保存6个月。本章节介绍如何使用javaagent方式接入NUWA Trace Agent，接入后可以在“Agent管理”页面查看已接入的NUWA Trace Agent信息。

前提条件

已获取访问密钥，具体请参见新增访问密钥。

约束与限制

  • 仅支持Java开发的微服务。
  • 不支持与其他javaagent的调用链一起集成。 在集成NUWA Trace前，需要删除其他调用链的javaagent参数。可以检查业务的java进程参数，是否有多个javaagent的调用链信息。

操作流程

  1. 部署NUWA Trace Agent：部署NUWA Trace Agent，用于调用链日志记录埋点，即通过修改业务Java程序的字节码实现。 部署成功后会生成/opt/huawei/apps/common/nuwa-tracer目录。
  2. 为业务进程添加启动参数：业务运行进程中，需包含如下所示的javaagent启动参数。 
    -javaagent:/opt/huawei/apps/common/nuwa-tracer/nuwa-tracer-javaagent.jar=微服务名

容器场景接入NUWA Trace Agent

  1. 部署NUWA Trace Agent。

    • 使用NUWA SDK

      使用3.0.3.101及以上版本的NUWA基础镜像，已内置Trace Agent，无需再部署。由于NUWA基础镜像版本发布节奏与NUWA Trace不一致，因此并不是每一个Trace版本都有一个对应的镜像版本。推荐选择最新的镜像版本。

    • 不使用NUWA SDK

      推荐在Docker构建阶段安装agent，参考脚本如下：

      # 构建脚本
wget https://xxx/xx/xx.zip  下载agent
packageName=$(ls nuwa-tracer-javaagent*.zip)
mkdir nuwa-tracer
unzip ${packageName} -d nuwa-tracer
# Dockerfile脚本 需要将Trace Agent copy到镜像中
COPY --chown=1001:2001 nuwa-tracer /opt/huawei/apps/common/nuwa-tracer

  2. 为业务进程添加启动参数。

    检查启动参数是否添加成功，通过ps -ef | grep nuwa-tracer检查其javaagent参数是否存在。

虚拟机场景接入NUWA Trace Agent

  1. 部署NUWA Trace Agent，将NUWA Trace部署包部署到服务器。

    • IAC部署
      1. 在微服务的IaC tfDefinition中增加NUWA Trace部署步骤定义step_install-nuwa-tracer。 
        locals {
  step_install-nuwa-tracer = {
    name = "install-nuwa-tracer"
    playbook = "playbook/common/nuwa-tracer-install/1.0.9"
    inputs = {
      agent_scope = "nuwa"  # agent所在领域，固定为nuwa
      business_scope = var.scope_name  # 业务所在领域
      cluster_name = var.cluster_name  # 集群名
      # NUWA Trace Agent版本见ReleaseNotes： https://console.wisedevops.huawei.com/operation/doc/000007003/999116103324041094
      agent_version = "1.0.18.100"  # NUWA Trace Agent版本，请修改为所需安装的版本
      # 应用市场接入研发镜像环境需设置agent_conf_version = "1.0.2.101.mirror"， 其他业务或环境无需设置（使用默认值为"1.0.2.101"）；
    }
  }
}
      2. 将如下步骤添加到业务部署步骤之中，确保NUWA Trace在业务进程启动前已完成部署。该步骤没有其他依赖，可在deploy_steps第一步执行。 
        module "cluster" {
 source = "http://registry/tfdefinition/Resource/LegacyMicroServiceCluster/1.0"
 ...
 deploy_steps = concat(
   var.install_nuwa_tracer ? [local.step_install-nuwa-tracer] : [],
   xxx // 其他步骤
 )
 ...
}
      3. 在业务的部署模板中添加步骤，使用nuwa-tracer-install部署包进行NUWA Tracer安装，如创建部署模板所示，部署包选择“nuwa-tracer-install”。需在业务部署步骤前，可置于第一步，并设置正确的业务领域（business_scope）、集群名（cluster_name）和NUWA Trace Agent安装版本（agent_version）。
    • 非IAC部署
      1. 访问https://OBS环境域名/WiseCloudTraceSErvice/NUWA Trace Agent版本号，下载NUWA Trace Agent，其中OBS环境域名及NUWA Trace Agent版本号信息请参见表1。
        表1 参数信息说明

        运维中心环境

        OBS环境域名

        NUWA Trace Agent版本号

        中国区

        appstage-wiseeye-fuxirelase-cnnorth4.obs.cn-north-4.myhuaweicloud.com

        24.11.0/24.11.300.12051711/nuwa-tracer-javaagent_24.11.0.zip
      2. 将Agent解压到/opt/huawei/apps/common/nuwa-tracer/
      3. 修改config/nuwa-tracer.properties、 config/tracer-credential.properties配置。
        config/nuwa-tracer.properties配置 
        # config/tracer-credential.properties
master.address=https://tracer-config.huawei.com:21255 # 调用链配置管理微服务地址
collector.address=wss://collector-server.huawei.com:21156 # 调用链数据采集微服务地址
agent.basic.metric.enable=true
agent.enable=true
basic.trace.debug.enable=false
sts.config.path=                     # 如果SK使用ACMS加密，需要配置STS密钥ini文件绝对路径
sts.cert.path=/opt/huawei/certs/
###########################################################
# tomcat config                                           #
###########################################################
tomcat.exclude.url=/**/*.css,/**/*.jpg,/**/*.png,/**/*.js,/**/*.html
###########################################################
# kafka config                                           #
###########################################################
plugin.kafka.header.enable=false
        config/tracer-credential.properties配置 
        access.key=     # 访问密钥AK值，无需加密保存
secret.key=    # 访问密钥Secret值，建议加密保存
decrypt.className=     # 自定义secret解密算法类路径
decrypt.methodName=    # 自定义secret解密算法的方法名称
sts.server.domain=    # 如果使用ACMS加密secret，需要配置ACMS sts server地址

  2. 为业务进程添加启动参数。

    • NUWA框架（NUWA SDK版本 >=3.0.2.101）开发的微服务

      已默认集成所需的启动项，业务只需要在启动脚本bin/start.sh中增加开启调用链的开关和微服务名参数，参考如下：

      export TRACER_AGENT_SWITCH="ON"
export TRACER_MICROSERVICE_NAME="微服务名"
# 如果一个VM部署有多个进程同时接入NUWA Tracer（如多个微服务合设到一个VM，或一个微服务含多个实例），需显式地设置TRACER_CLUSTER_NAME集群名以区分，其他情况不要打开。
# export TRACER_CLUSTER_NAME="集群名"   #仅需要时才打开，正常从部署参数获取，一般不需要显示设置。
    • 非NUWA框架开发的微服务或NUWA框架（NUWA SDK版本 <3.0.2.101）开发的微服务

      在业务的启动脚本（如bin/start.sh）中增加-javaagent参数，参考如下：

      # ----------------- NUWA Tracer begin-----------------------------
# - TRACER_AGENT_SWITCH 开关，ON表示启用Tracer
# - TRACER_MICROSERVICE_NAME 微服务名称
TRACER_AGENT_SWITCH="ON"
# 修改成业务的微服务
TRACER_MICROSERVICE_NAME="微服务名"
# 如果一个VM部署有多个进程同时接入NUWA Tracer（如多个微服务合设到一个VM，或一个微服务含多个实例），需显式地设置TRACER_CLUSTER_NAME集群名以区分，其他情况不要打开。
# TRACER_CLUSTER_NAME="集群名"   #仅需要时才打开，正常从部署参数获取，一般不需要显示设置。
TRACER_AGENT_JAR="/opt/huawei/apps/common/nuwa-tracer/nuwa-tracer-javaagent.jar"
if [ "X$TRACER_AGENT_SWITCH" = "XON" ]; then
    #用来检查NUWA Tracer的jar包是否存在，jar包存在才能添加启动参数。
    if [ ! -f $TRACER_AGENT_JAR ]; then
        echo "NUWA Tracer agent jar can't be found!"
    elif [ "X$TRACER_MICROSERVICE_NAME" = "X" ]; then
        echo "NUWA Tracer agent switch is ON, but TRACER_MICROSERVICE_NAME is not set"
    else
        TRACER_AGENT_ARGS=$TRACER_MICROSERVICE_NAME
        if [ "X$TRACER_CLUSTER_NAME" != "X" ]; then
            TRACER_AGENT_ARGS="$TRACER_AGENT_ARGS,$TRACER_CLUSTER_NAME"
        fi
        TRACER_AGENT_PARAM="-javaagent:$TRACER_AGENT_JAR=$TRACER_AGENT_ARGS"
        echo "NUWA Tracer agent switch is ON, and TRACER_AGENT_PARAM is $TRACER_AGENT_PARAM"
        #添加JAVA_OPTS到进程启动参数。启动后，通过 ps -ef | grep nuwa-tracer 命令，查看配置是否生效
        export JAVA_OPTS=$TRACER_AGENT_PARAM
    fi
else
    echo "NUWA Tracer agent switch is OFF!"
fi
# ----------------- NUWA Tracer end -------------------------------

相关文档