# Sermant-agent使用手册

sermant-agent为Sermant必要核心组件，包含sermant-agentcore (opens new window)、sermant-plugins (opens new window)、sermant-common (opens new window)等字节码增强逻辑的实现主体。Sermant使用介绍中描述的产品目录sermant-agent-x.x.x/agent目录下内容即为sermant-agent组件的各模块。本文介绍如何使用sermant-agent。

sermant-agent的框架主体为Sermant提供了字节码增强的实现逻辑，同时支持心跳功能、动态配置功能、日志功能等公共核心能力。sermant-agent插件包中则由各扩展插件提供了标签路由、限流降级、双注册等服务治理能力。

# 参数配置

在Java程序启动时，通过 -javaagent参数指定sermant-agent.jar的文件路径，即可使该Java程序(也称为宿主应用)在运行时挂载sermant-agent。sermant-agent.jar在Sermant打包后产品包的agent/sermant-agent.jar路径中存放。

-javaagent:sermant-agent.jar[=${options}]

其中${options}为启动参数，会作为premain方法的入参agentArgs传入。

public static void premain(String agentArgs, Instrumentation inst);

参数agentArgs的格式要求形如key1=value1,key2=value2[(,keyN=valueN)...]，以','分割键值对，以'='分割键值，形成Map结构。

# Sermant-agent启动参数

启动参数配置参考如下：

入参agentArgs中也可以为启动参数配置自定义的值。

此外，启动参数也可在sermant-agent的产品包下agent/config/bootstrap.properties中配置，配置参考与上述一致，同时也支持增加自定义启动参数。

# Sermant-agent使用参数配置

Sermant除插件配置外的其他配置都在sermant-agent的产品包下agent/config/config.properties中配置。各插件的参数配置请参考插件使用手册 (opens new window)中相关描述。

# agent config
agent.config.isEnhanceBootStrapEnable=false
agent.config.ignoredPrefixes=com.huawei.sermant,com.huaweicloud.sermant
agent.config.ignoredInterfaces=org.springframework.cglib.proxy.Factory
agent.config.combineStrategy=ALL
agent.config.serviceBlackList=com.huaweicloud.sermant.implement.service.heartbeat.HeartbeatServiceImpl,com.huaweicloud.sermant.implement.service.send.NettyGatewayClient,com.huaweicloud.sermant.implement.service.tracing.TracingServiceImpl
agent.config.serviceInjectList=com.huawei.discovery.service.lb.filter.NopInstanceFilter,com.huawei.discovery.service.lb.DiscoveryManager
agent.config.isShowEnhanceLogEnable=false
agent.config.enhancedClassOutputPath=

# dynamic config
dynamic.config.timeoutValue=30000
dynamic.config.defaultGroup=sermant
dynamic.config.serverAddress=127.0.0.1:2181
dynamic.config.dynamicConfigType=ZOOKEEPER
dynamic.config.connectRetryTimes=5
dynamic.config.connectTimeout=1000
dynamic.config.userName=
dynamic.config.password=
dynamic.config.privateKey=
dynamic.config.enableAuth=false

# heartbeat config
heartbeat.interval=30000

# backend config
backend.nettyIp=127.0.0.1
backend.nettyPort=6888

# service meta config
service.meta.application=default
service.meta.version=1.0.0
service.meta.project=default
service.meta.environment=
service.meta.zone=
service.meta.parameters=

# service visibility config
visibility.service.enableStart=false

其中涉及的参数与sermant-agent、Backend、动态配置中心等有关联，具体参数配置参考下面说明。

# agent框架相关参数

# 动态配置中心相关参数

# Backend相关参数

# 服务元数据相关参数

# 插件相关参数

# Sermant-agent挂载插件配置

Sermant自定义选择挂载哪些插件可在sermant-agent的产品包下agent/config/plugins.yaml中配置，配置方式如下：

plugins:                 # 可自定义配置默认挂载的插件名称
  - flowcontrol
  - service-router
  - service-registry
  - loadbalancer
  - dynamic-config
  - monitor
  - springboot-registry
  - mq-consume-deny
profiles:                # profiles自定义不同场景需配置挂载的插件列表
  cse:
    - flowcontrol
    - service-router
    - service-registry
    - dynamic-config
  apm:
    - flowcontrol
    - service-router
profile: cse,apm         # profile用于按场景配置挂载的插件列表，此处配置生效的场景

其中各参数配置说明如下：

启动时，plugins 下配置的插件都会挂载至宿主应用，profile下的插件列表也可按需配置生效。

插件的加载顺序

Sermant插件的加载顺序如下：

1. 首先按照plugins中配置的插件顺序来加载默认插件。
2. 然后再按照profile配置的场景顺序来加载场景插件列表，各场景的插件加载顺序也和配置文件中的顺序一致。
3. 如果profiles中的配置的插件已经在之前加载过，则不再重复加载。
4. 不同插件的相同拦截点的字节码增强的生效顺序与插件加载顺序是一致的。

# 参数配置方式

Sermant项目sermant-agent的properties配置文件和各插件的中yaml配置文件都支持下列几种参数配置方式，以配置文件中的backend.nettyIp=127.0.0.1为例：

1. 直接修改配置文件，即在配置文件中修改backend.nettyIp=127.0.0.1
2. 通过应用启动时的-D参数配置，即-Dbackend.nettyIp=127.0.0.1
3. 通过环境变量配置，即在环境变量中新增backend.nettyIp=127.0.0.1
4. 通过sermant-agent启动参数配置，即-javaagent:sermant-agent.jar=backend.nettyIp=127.0.0.1

以上四种方式，配置生效的优先级从高到低排列为：4 > 3 > 2 > 1。

其中，后三种参数配置值的获取方式支持多种格式，以配置文件中的backend.nettyIp=127.0.0.1为例，下列配置格式都可识别：

backend.nettyIp=127.0.0.1
backend_nettyIp=127.0.0.1
backend-nettyIp=127.0.0.1
BACKEND.NETTYIP=127.0.0.1
BACKEND_NETTYIP=127.0.0.1
BACKEND-NETTYIP=127.0.0.1
backend.nettyip=127.0.0.1
backend_nettyip=127.0.0.1
backend-nettyip=127.0.0.1
backend.netty.ip=127.0.0.1
backend_netty_ip=127.0.0.1
backend-netty-ip=127.0.0.1
BACKEND.NETTY.IP=127.0.0.1
BACKEND_NETTY_IP=127.0.0.1
BACKEND-NETTY-IP=127.0.0.1

sermant-agent将从上至下依次检索各项配置值是否通过启动参数、环境变量、-D参数来配置。

注意： 通过容器场景的env修改配置，请将点（.）可用下划线（_）替代！！！

原因：因为一些OS镜像无法识别带 . 的env

举个例子：如需想通过pod的env修改配置文件中的backend.nettyIp=127.0.0.1则

  env:
  - name: "backend_nettyIp"
    value: "127.0.0.2"

# 支持版本

# sermant-agent 支持的版本

sermant-agent支持Linux、Windows、Aix操作系统,支持JDK 1.6及以上版本，建议使用JDK 1.8版本。

• HuaweiJDK 1.8 (opens new window) / OpenJDK 1.8 (opens new window) / OracleJDK 1.8 (opens new window)

# 启动和结果验证

# 启动

以Sermant-example项目 demo-application (opens new window)为宿主应用，执行以下命令挂载sermant-agent启动demo-application:

# Run under Windows
java -javaagent:sermant-agent-x.x.x\agent\sermant-agent.jar=appName=test -jar demo-application.jar

# Run under Linux
java -javaagent:sermant-agent-x.x.x/agent/sermant-agent.jar=appName=test -jar demo-application.jar

# 验证

查看demo-application的日志文件开头是否包含以下内容：

[INFO] Loading core library... 
[INFO] Building argument map... 
[INFO] Loading sermant agent... 
[INFO] Load sermant done. 

若日志如上正常输出，则说明sermant-agent挂载成功。