# Sermant-agent User Manual

Sermant-agent is the essential core component of Sermant, which contains bytecode enhancements of sermant-agentcore (opens new window), sermant-plugins (opens new window), sermant-common (opens new window). The modules of the sermant-agent component are found in the sermant-agent-x.x.x/agent directory described in the Sermant Introduction. This article describes how to use sermant-agent.

The framework body of sermant-agent provides bytecode enhanced implementation logic for Sermant, and supports common core capabilities such as heartbeat function, dynamic configuration function and log function. In the sermant-agent plugin package, the extension plugins provide the service governance capabilities such as label routing, flow control and double registration.

# Parameter Configuration

Specify sermant-agent.jar via the -javaagent parameter when a Java program (Java class with a main function) is running. sermant-agent.jar is deposited in agent/sermant-agent.jar of sermant-agent pruduct package.

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

Where ${options} is the launch input parameter, which will be transferred as the parameter agentArgs to the premain method.

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

The format of the agentArgs parameter should look like key1=value1,key2=value2[(,keyN=valueN)...], which splits key/value pairs with ',', and splits between key and value with '=' 'to form a Map structure.

# Sermant-agent Startup Parameters

The startup parameters are listed as follows:

The agentArgs parameter allows you to configure more custom values for startup parameters.

In addition, the startup parameters can also be configured in agent/config/bootstrap properties in the product package of sermant-agent, which are consistent with the parameters above and also supports custom startup parameters.

# Sermant-agent Parameter Configuration

All other configurations beside plugin configurations are configured in the agent/config/config.properties of the sermant-agent product package. Please refer to the Plugin Guide (opens new window) for configurations of each plugin.

# 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

The parameters involved are associated with sermant-agent, Backend, Dynamic Configuration Center, etc. Refer to the following tables for specific parameter configurations.

# Parameters Related to Agent Framework

# Parameters Related to Dynamic Configuration Center

# Parameters Related to Backend

# Parameters Related to Service Metadata

# Plugin related parameters

# Sermant-agent Mounted Plugins Configuration

You can configure which plugins to be mounted by Sermant in agent/config/plugins.yaml of sermant-agent product package.For example:

plugins:                 # You can customize the plugins to be mounted by default
  - flowcontrol
  - service-router
  - service-registry
  - loadbalancer
  - dynamic-config
  - monitor
  - springboot-registry
  - mq-consume-deny
profiles:                # You can configure the list of plugins mounted of each profile
  cse:
    - flowcontrol
    - service-router
    - service-registry
    - dynamic-config
  apm:
    - flowcontrol
    - service-router
profile: cse,apm         # Profile is used to configure the list of mounted plugins by scenario. You can configure the in effect

The parameters are described as follows:

Any plugins configured in plugins will be mounted to the host application at startup. The list of plugins in profile can also be configured on demand.

Loading order of plugins

The Sermant plugin loads in the following order:

1. First load the default plugins in the order configured in plugin.

2. Then load the scenario plugin list according to the scenario sequence configured in profile. The scenario plugin loading sequence is the same as that in the configuration file.

3. If the plugin configured in profiles has been loaded before, it will not be loaded again.

4. Bytecode enhancements at the same interception point for different plugins take effect in the same order as plugin loading.

# Parameter Configuration Options

The sermant project's properties configuration file and yaml configuration file for sermant-agent plugins support the following configuration options. Take backend.nettyIp=127.0.0.1 in the configuration file for example:

1. Modify the configuration file directly, via configure backend.nettyIp=127.0.0.1 in the configuration file.
2. Configure the -D option at startup, like: -Dbackend.nettyIp=127.0.0.1.
3. Configure via environment variables, via add backend.nettyIp=127.0.0.1 to environment variables.
4. Configure startup parameters of sermant-agent, like: -javaagent:sermant-agent.jar=backend.nettyIp=127.0.0.1

The configuration takes effect in descending order of priority: 4 > 3 > 2 > 1.

The last three ways to obtain configuration parameters support various formats. Take backend.nettyIp=127.0.0.1 in the configuration file for example, the following configuration formats can be identified:

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

The sermant-agent retrieves, from top to bottom, whether the configuration values are configured by startup parameter, the environment variable, and the -D parameter.

# Versions Supported

Sermant-agent supports Linux, Windows, and Aix operating systems, supports JDK 1.6 and above, and recommends using JDK 1.8.

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

# Startup and Result Validation

# Startup

Start with a Sermant-example project [demo-application] (https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/demo-application) as the host application, execute the following command to mount the sermant-agent and start 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

# Validation

Check to see if the log file for demo-application starts with the following:

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

If the log output is normal, then the sermant-agent was mounted successfully.