# 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启动参数

启动参数配置参考如下：

应用：完成某项完整业务场景的软件系统。应用一般由多个微服务组成，应用里面的微服务能够相互发现和调用。

微服务：微服务是业务概念，即提供某种服务的某个进程。每一个服务都具有自主运行的业务功能，对外开放不受语言限制的API (最常用的是HTTP)。

入参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.serviceInjectList=com.huawei.discovery.service.lb.filter.NopInstanceFilter,com.huawei.discovery.service.lb.DiscoveryManager,com.huawei.discovery.service.util.ApplyUtil,com.huawei.discovery.service.lb.cache.InstanceCacheManager
agent.config.isOutputEnhancedClasses=false
agent.config.enhancedClassesOutputPath=
agent.config.isShowEnhanceLog=false

# agent service config
agent.service.heartbeat.enable=false
agent.service.gateway.enable=false
agent.service.tracing.enable=false
agent.service.visibility.enable=false
agent.service.inject.enable=true
agent.service.monitor.enable=false
agent.service.dynamic.config.enable=true

# event config
event.enable=false
event.offerWarnLog=false
event.offerErrorLog=false
event.sendInterval=30000
event.offerInterval=300000

# 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

# gateway config
gateway.nettyIp=127.0.0.1
gateway.nettyPort=6888
gateway.nettyConnectTimeout=5000
gateway.nettyWriteAndReadWaitTime=60000
gateway.sendInternalTime=10
gateway.initReconnectInternalTime=5
gateway.maxReconnectInternalTime=180

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

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

# 字节码增强参数

# 核心服务开关

下述配置用于控制框架提供的各核心服务的开启和关闭：

# 事件上报参数

下述配置用于控制框架提供的事件系统：

# 动态配置中心参数

下述配置为控制与动态配置中心连接时的可自定义属性：

# 心跳服务参数

# 网关服务参数

下述配置用于控制在通过网关服务和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
  - service-removal
  - service-visibility
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配置文件都支持下列几种参数配置方式，以配置文件中的gateway.nettyIp=127.0.0.1为例：

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

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

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

gateway.nettyIp=127.0.0.1
gateway_nettyIp=127.0.0.1
gateway-nettyIp=127.0.0.1
GATEWAY.NETTYIP=127.0.0.1
GATEWAY_NETTYIP=127.0.0.1
GATEWAY-NETTYIP=127.0.0.1
gateway.nettyip=127.0.0.1
gateway_nettyip=127.0.0.1
gateway-nettyip=127.0.0.1
gateway.netty.ip=127.0.0.1
gateway_netty_ip=127.0.0.1
gateway-netty-ip=127.0.0.1
GATEWAY.NETTY.IP=127.0.0.1
GATEWAY_NETTY_IP=127.0.0.1
GATEWAY-NETTY-IP=127.0.0.1

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

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

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

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

  env:
  - name: "gateway_nettyIp"
    value: "127.0.0.2"

# 支持版本

# sermant-agent 支持的版本

sermant-agent支持Linux、Windows，基于JDK 1.8开发，建议使用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挂载成功。