Logging Function

This article describes how to use the logging system provided by Sermant in your development.

Function Introduction

Log is an indispensable ability in program development, through the log can quickly find out the state of the program running and the problems encountered. Sermant log system is built on JUL&logback, which provides a complete, flexible configuration log tool to avoid class conflicts for plugin development.

Note: Based on Sermant's class isolation strategy, the log system constructs the log through JUL interface and outputs the log through logback engine. This is due to the jul-to-slf4j (opens new window) bridging capability, based on which you don't have to worry about logging configuration and output conflicts with the enhanced application.

Development Examples

This development example is based on the project created in the Create your first plugin document.

Find template\template-plugin under com.huaweicloud.sermant.template.TemplateDeclarer class, in which define a private static constants LOGGER, used in the class of log structure:

private static final java.util.logging.Logger LOGGER = LoggerFactory.getLogger();

Then we are in for main method Interceptor before and after method through java.util.logging.Logger::info interface added INFO level of execution This will allow us to see the interceptor execution in the log:

@Override
public ExecuteContext before(ExecuteContext context) throws Exception {
    LOGGER.info("Say good morning before good afternoon!");
    System.out.println("Good morning!");
    return context;
}

@Override
public ExecuteContext after(ExecuteContext context) throws Exception {
    LOGGER.info("Say good night after good afternoon!");
    System.out.println("Good night!");
    return context;
}

Once the development is complete, follow the Packaged build process used to create the first plugin, run mvn package in the root directory of the project, and run cd agent/ in it with Sermant to run the test app. Run java -javaagent:sermant-agent.jar -jar Application.jar

$ java -javaagent:sermant-agent.jar -jar Application.jar
[xxxx-xx-xxTxx:xx:xx.xxx] [INFO] Loading god library into BootstrapClassLoader.
[xxxx-xx-xxTxx:xx:xx.xxx] [INFO] Building argument map by agent arguments.
[xxxx-xx-xxTxx:xx:xx.xxx] [INFO] Loading core library into SermantClassLoader.
[xxxx-xx-xxTxx:xx:xx.xxx] [INFO] Loading sermant agent, artifact is: default
[xxxx-xx-xxTxx:xx:xx.xxx] [INFO] Load sermant done, artifact is: default
Good morning!
Good afternoon!
Good night!

The execution logic defined in the plug-in has been enhanced into the test application. Next, take a look at the logs generated while the program is running:

1. Enter the log directory by running cd logs/sermant/core/app/${yyyy-mm-dd}/, where ${yyyy-mm-dd} refers to the directory name generated by the runtime based on the date.

2. Open the log file sermant-0.log to check the log content. We can see that the log we constructed has taken effect, and we can see the trigger time, log level, class, method, line of code, thread and other information in the log, which is easy to understand the running state of the program.

xxxx-xx-xx xx:xx:xx.xxx [INFO] [com.huaweicloud.sermant.template.TemplateDeclarer$1] [before:33] [main] Say good morning before good afternoon!
xxxx-xx-xx xx:xx:xx.xxx [INFO] [com.huaweicloud.sermant.template.TemplateDeclarer$1] [after:40] [main] Say good night after good afternoon!

API & Configuration

API

Get Logging Tools

• Get the logging tool object for constructing logs in development. The log instance is a java.util.logging.Logger instance, which has been initialized and bridged to the logback logging engine in the Sermant framework.

java.util.logging.Logger LOGGER = LoggerFactory.getLogger();

Logging

Developers can use the following logging interfaces to record various levels (TRACE, DEBUG, INFO, WARN, ERROR) of execution to achieve different levels of monitoring.

• Record TRACE level logs to trace detailed program execution flow. This level is off by default, but it needs to be configured if needed.

java.util.logging.Logger LOGGER = LoggerFactory.getLogger();
LOGGER.finest("TRACE MESSAGE");

• Logging at the DEBUG level, used to record details at key points in the application, possibly containing method arguments or return values, which can be used to learn more about the application during debugging. This level is off by default, but it needs to be configured if needed.

java.util.logging.Logger LOGGER = LoggerFactory.getLogger();
LOGGER.fine("DEBUG MESSAGE");

• Logging INFO level logs, used to record some critical information about the program execution, often to indicate where the program has entered or the state of the execution, often not like the detailed information recorded in DEBUG level logs.

java.util.logging.Logger LOGGER = LoggerFactory.getLogger();
LOGGER.info("INFO MESSAGE");

• Log at the WARN level to log some warning messages. Some special states are entered during the running of the logger. Although they will not affect the running of the program, they are worth noting.

java.util.logging.Logger LOGGER = LoggerFactory.getLogger();
LOGGER.warning("WARN MESSAGE");

• the record level of the ERROR log, to record the ERROR in the operation of the program, used to provide information to facilitate the development and maintenance personnel to understand the causes of ERROR.

java.util.logging.Logger LOGGER = LoggerFactory.getLogger();
LOGGER.severe("ERROR MESSAGE");

Configuration

The logging system provided by Sermant is based on the logback logging engine and follows logback's logging configuration style, based on the Project structure created in the first plugin, by modifying the config/logback.xml to customize the logging logic.

Log Output Configuration

Configuration Items	Description	Example Configuration
log.home_dir	Used to specify the final log output path.	${sermant_log_dir:-./logs/sermant/core}
log.app_name	The filename prefix used to specify the log file.	{sermant_app_name:-sermant}
log.maxHistory	Used to specify the maximum duration (in days) of the log file.	${sermant_log_max_history:-30}
log.level	Used to specify the minimum level of log output, configurable trace、debug、info、warn、error。	${sermant_log_level:-trace}
log.maxSize	Used to specify the maximum capacity of a single log file.	${sermant_log_max_size:-5MB}
log.totalSize	Used to specify the maximum total capacity of the log file.	${sermant_log_total_size:-20GB}
log.pattern	Used to specify the format of the output log.	%d{yyyy-MM-dd HH:mm:ss.SSS} [%le] [%C] [%M:%L] [%thread] %m%n

Note: All configuration values support reading the configuration from an environment variable, simply configure it as ${environment variable name:-default value}. The format of the output log is configured in Log Format Configuration.

Log Format Configuration

Log the default configuration for %d{yyyy-MM-dd HH:mm:ss.SSS} [%le] [%C] [%M:%L] [%thread] %m%n identification meaning which can be configured as follows:

Configuring Identity	Description
%d	Used to specify the date format for log output.
%C	Use to specify the full class name of the class in which the log output occurred.
%F	The filename used to specify the log output class in which the log occurs.
%M	The name of the method used to specify the log output for which the log occurred.
%L	Line number used to specify the log output in the class where the log occurred.
%thread	Used to specify the log output thread on which the log occurred.
%m	Used to specify that the log outputs the information specified when the log was constructed.
%n	Newline characters