# 接入NUWA Trace Agent
使用javaagent方式接入NUWA Trace Agent，采集调用链类数据及指标类数据，数据保留期为7天，并按小时和天级进行聚合存储到MPPDB中，保存6个月。本章节介绍如何使用javaagent方式接入NUWA Trace Agent，接入后可以在"Agent管理"页面查看已接入的NUWA Trace Agent信息。
#### 前提条件
已获取访问密钥，具体请参见[新增访问密钥](https://support.huaweicloud.com/usermanual-wiseeye/wiseeye_04_0015.html)。
#### 约束与限制
- 仅支持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. 为业务进程添加启动参数。 
   - **带NUWA SDK或Tomcat的NUWA基础镜像**
     修改IAC3.0 环境变量文件（如envs.yaml），参考如下：
     ```
     - name: TRACER_AGENT_SWITCH   
       value: 'ON'
     ```
     
   
   - **不带NUWA SDK的NUWA基础镜像**
     请参考[虚拟机场景为非NUWA框架业务进程添加启动参数]。
     
   
   
   检查启动参数是否添加成功，通过**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安装，如[创建部署模板](https://support.huaweicloud.com/usermanual-wiseeye/appstage_04_0123.html#section1)所示，部署包选择"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 -------------------------------
     ```