7.1. Log Output¶

7.1.1.1. Implementation of the log output function can be replaced¶

The log output is composed of three processes, and the implementation of each of which can be replaced.

Can be replaced with the LogWriter and LogFormatter units, and if these do not meet the requirements Logger / LoggerFactory can be implemented to replace almost all processes.

For example, if the use of open source log output library is preferred, replacing Logger / LoggerFactory is better.

Note that the logging framework with extensive operating experience in open source, is already equipped with a dedicated logger/logger factory.

For details, see log Adapter .

For comparison of features between this function and the frequently utilized log4j, see Functional comparison with log4j .

The default class provided by the log output function is shown.

Logger/LoggerFactory

• BasicLogger
• BasicLoggerFactory

LogWriter

• FileLogWriter (Output to file. Log rotation)
• SynchronousFileLogWriter (output from multiple processes to one file)
• StandardOutputLogWriter (output to standard output)
• LogPublisher (output to any listener)

LogFormatter

• BasicLogFormatter (format by pattern string)

RotatePolicy

• DateRotatePolicy (Log rotation by date and time)
• FileSizeRotatePolicy (Log rotation by file size)

7.1.1.2. Provides various log output functions in advance¶

This framework provides the output function of various logs commonly required by the applications. The log format can be changed with configuration and used according to the application requirements. As described in the Configure various logs, the output function of various logs is performing formatting only, and this function is used for the output processing of the logs. The blank project generated from the archetype provided by Nablarch has various log formats set. See Default configuration list for more information.

7.1.3.1. Output the log.¶

Use Logger to output logs Get Logger from LoggerManager .

// Get logger by specifying a class.
// Logger is stored in class variable.
private static final Logger LOGGER = LoggerManager.get(UserManager.class);

// Check the log output in advance and output the log.
if (LOGGER.isDebugEnabled()) {
    String message = "userId[" + user.getId() + "],name[" + user.getName() + "]";
    LOGGER.logDebug(message);
}

Specify the logger name in the acquisition of Logger . A string or class can be specified for the logger name. If a class is specified, FQCN of the specified class will be the logger name.

7.1.3.2. Configure log output¶

Configure the log output in the property file.

Property file location

Use log.properties directly below the classpath. If the location is to be changed, specify the file path in the system property with nablarch.log.filePath as a key. See FileUtil#getResource how to specify file path.

>java -Dnablarch.log.filePath=classpath:nablarch/example/log.properties ...

Description rules of property files

The description rules of the property file are shown below.

LoggerFactory

Description rules

loggerFactory.className

Specify FQCN of the class that implements loggerFactory.className LoggerFactory. To use this function, specify BasicLoggerFactory .

Example of the description

# LoggerFactory determines the implementation (this function, Log4J, etc.) used for log output.
loggerFactory.className=nablarch.core.log.basic.BasicLoggerFactory

LogWriter

Description rules

writerNames

Specify the names of all LogWriters that use writerNames. Use comma as a delimiter if more than one is specified.

writer. <name>.className

Specify FQCN of the class that implemented LogWriter.

writer. <name>.<property name>

Specify the value to be set in the property for each LogWriter. Refer to Javadoc of the LogWriter used for the properties that can be specified.

Example of the description

# Define 2 names.
writerNames=appLog,stdout

# Configure appLog.
writer.appLog.className=nablarch.core.log.basic.FileLogWriter
writer.appLog.filePath=/var/log/app/app.log

# Configure stdout.
writer.stdout.className=nablarch.core.log.basic.StandardOutputLogWriter

Logger configuration

Description rules

availableLoggersNamesOrder

Specify the names of all Logger configurations that use availableLoggersNamesOrder. Use comma as a delimiter if more than one is specified.

Important

Note that the order of description in the availableLoggersNamesOrder property has a meaning.

The acquisition process Logger matches Logger in the order described here for the logger name specified by the class that performs log output and returns the first match Logger .

For example, if the description order of availableLoggersNamesOrder in the following description example is described as availableLoggersNamesOrder = root, sql, all logger acquisitions will end up matching the logger configuration root . As a result, even if the log is output with the logger name SQL , the log is not output to sqlLog but is output to the appLog specified in the logger configuration root .

Therefore, the availableLoggersNamesOrder property is described in sequence from the logger configuration that specifies a more restrictive regular expression.

Important

The names of the logger configuration specified in the availableLoggersNamesOrder and loggers.* are required to match. The match is checked in the initial process of BasicLoggerFactory , and an exception is thrown if they do not match. For example, if access is removed from availableLoggersNamesOrder in the above configuration, an exception will be thrown.

This check is performed to avoid the occurrence of configuration omissions. If access is removed from avaialableLoggersNameOrder in the above configuration, it is necessary to explicitly remove the loggers.access.* configuration.

loggers.<name>.nameRegex

loggers.<name>.nameRegex specifies the regular expression used to match the logger name. The regular expressions are used to narrow down the loggers that are the targets of logger configuration. Matched to logger name specified when acquiring the logger (that is, the logger name specified in the argument of LoggerManager#get).

loggers.<name>.level

Specify the name of loggers.<Name>.level LogLevel . All the logs that are above the level specified here will be output.

loggers.<name>.writerNames

loggers.<name>.writerNames specifies the name of the LogWriter, which is the output destination. Use comma as a delimiter if more than one is specified. Logs are written for all the LogWriters specified here.

Example of the description

# Define the names of the two logger configurations.
availableLoggersNamesOrder=sql,root

# Set root.
loggers.root.nameRegex=.*
loggers.root.level=WARN
loggers.root.writerNames=appLog

#Set sql.
loggers.sql.nameRegex=SQL
loggers.sql.level=DEBUG
loggers.sql.writerNames=sqlLog

Description example of property files

A description example of the entire property file is shown below.

loggerFactory.className=nablarch.core.log.basic.BasicLoggerFactory

writerNames=appLog,sqlLog,monitorLog,stdout

# Example of configuring a log file for application
writer.appLog.className=nablarch.core.log.basic.FileLogWriter
writer.appLog.filePath=/var/log/app/app.log

# Example of configuring a log file for SQL output
writer.sqlLog.className=nablarch.core.log.basic.FileLogWriter
writer.sqlLog.filePath=/var/log/app/sql.log

# Example of configuring a log file for monitoring
writer.monitorLog.className=nablarch.core.log.basic.FileLogWriter
writer.monitorLog.filePath=/var/log/app/monitoring.log

# Configuring example for standard output
writer.stdout.className=nablarch.core.log.basic.StandardOutputLogWriter

availableLoggersNamesOrder=sql,monitoring,access,validation,root

# Example of configuring all logger names for log output
# Output WARN level or higher to appLog for all logger acquisition.
loggers.root.nameRegex=.*
loggers.root.level=WARN
loggers.root.writerNames=appLog

# Example of configuring a specific logger name as a log output target.
# For logger acquisition with "MONITOR" specified in logger name
# Output ERROR level or higher to appLog, monitorLog.
loggers.monitoring.nameRegex=MONITOR
loggers.monitoring.level=ERROR
loggers.monitoring.writerNames=appLog,monitorLog

# Example of configuring a specific logger name as a log output target.
# For logger acquisition with "SQL" specified in logger name
# Output DEBUG level or higher to sqlLog.
loggers.sql.nameRegex=SQL
loggers.sql.level=DEBUG
loggers.sql.writerNames=sqlLog

# Example of configuring a specific class as a log output target.
# For logger acquisition with "app.user.UserManager" specified in logger name
# Output INFO level or higher to appLog and stdout.
loggers.access.nameRegex=app\\.user\\.UserManager
loggers.access.level=INFO
loggers.access.writerNames=appLog,stdout

# Configuration example for targeting specific packages and below for log output.
# For logger acquisition in which the name starting from "nablarch.core.validation" is specified in logger name
# output DEBUG level or higher to stdout.
loggers.validation.nameRegex=nablarch\\.core\\.validation\\..*
loggers.validation.level=DEBUG
loggers.validation.writerNames=stdout

Tip

Preparing one logger configuration that matches all the log output and specifying the logger configuration at the end of availableLoggersNamesOrder is recommended. Outputs of important logs are prevented from being missed even if the configuration is omitted. Refer to the logger configuration root in the above description example for the configuration example.

7.1.3.3. Overwrite log output configuration¶

The log output configuration can be overwritten by using system property and specifying the value with the same key name as the property file. By this, it is possible to prepare a common property file and change the log output configuration for each process.

Below is an example of how to change the log level of logger configuration root to INFO.

>java -Dloggers.root.level=INFO ...

7.1.3.4. Specify the log format¶

This function provides BasicLogFormatter as LogFormatter that can be used for general purpose.

Placeholders are used to specify the format in BasicLogFormatter . For placeholders that can be used, see BasicLogFormatter.

A configuration example for format is shown below. Specify the format in the LogWriter property.

# When specifying the format, specify BasicLogFormatter explicitly.
writer.appLog.formatter.className=nablarch.core.log.basic.BasicLogFormatter

# Specify the format using the placeholder.
writer.appLog.formatter.format=$date$ -$logLevel$- $loggerName$ $message$

# Specify the pattern to be used for date and time format.
#If not specified, "yyyy-MM-ddHH:mm:ss.SSS" is used.
writer.appLog.formatter.datePattern=yyyy/MM/dd HH:mm:ss[SSS]

# Specify the log level text
# If not specified, the LogLevel enumeration type (FATAL, INFO, etc.) names will be used.
writer.appLog.formatter.label.fatal=F
writer.appLog.formatter.label.error=E
writer.appLog.formatter.label.warn=W
writer.appLog.formatter.label.info=I
writer.appLog.formatter.label.debug=D
writer.appLog.formatter.label.trace=T

The following items can be output in BasicLogFormatter to identify the status of the output log. Descriptions are provided for these output items.

• Boot process
• Processing architecture
• Execution ID

Boot process

The boot process is the name used to identify the execution environment in which the application was started. By using a name that combines the server name and identification string such as JOBID for the boot process, the execution environment of the log output from multiple processes of the same server can be specified. The boot process is assumed to define a system such as an ID system for each project.

The boot process is specified in the system property with the nablarch.bootProcess key. If the system property is not specified, the boot process will be blank.

Processing architecture

Processing architecture refers to web, batch, etc. If the application process architecture is to be identified separately, it is specified and used for each project.

The process architecture is specified in the property file that was explained in Configure log output , with the key nablarch.processingSystem . If the property is not specified, it will be blank.

Execution ID

The execution ID is given with respect to the request ID to identify each execution of the application. Since the execution ID is issued based on the number of executions for one request ID, the relationship between request ID and run time ID is one to many.

When multiple logs are output, the execution ID is used to link the multiple logs that have been output.

The execution ID is issued at the timing of initializing : ThreadContext, and is configured in ThreadContext.

ID system for Execution ID

# Added only when the boot process is specified.
Boot process + system date and time (yyyyMMddHHmmssSSS) + serial number (4 digits)

When line feed code and tab character are to be included

When line feed code and tab character are to be included in the format, use the same description as Java shown below.

Line feed code \n
Tab character   \t

The line feed code is obtained from line.separator included in the system property of standard Java. Therefore, the OS line feed code is used if the line.separator in the system property is not changed.

Tip

Strings \n and \t cannot be output by BasicLogFormatter .

7.1.3.5. Configure various logs¶

The output function of each log only performs the format process according to the purpose of each log, and the process of log output uses this function. In other words, the message specified in Logger is created in the output function of various logs.

Therefore, to use the output function of various logs, configurations are required for various logs in addition to Configure log output . Configure various logs in the property file.

Property file location

Use app-log.properties directly below the classpath. If the location is to be changed, specify the file path in the system property with nablarch.appLog.filePath as a key. See FileUtil#getResource how to specify file path.

>java -Dnablarch.appLog.filePath=file:/var/log/app/app-log.properties ...

Description rules of property files

Refer to the following, as the rules differs for each log.

• Configure the failure log
• Configure the SQL log
• Configure performance log
• Configure the HTTP access log
• Configure the HTTP access log (for RESTful Web Service)
• Configure the messaging log

7.1.3.6. Rotate log files¶

FileLogWiter provided by this function rotates log files according to the configured policy.

The default rotation policy is FileSizeRotatePolicy which rotates by file size. By creating an implementation class of RotatePolicy, you can change the rotation policy.

The implementation class of RotatePolicy provided by this function is as follows. See the Javadoc for each RotatePolicy setting.

• FileSizeRotatePolicy
• DateRotatePolicy

An example of rotation policy setting is shown below. Rotation policy is specified in LogWriter property.

writerNames=sample

# Specify the FQCN of the class that implements RotatePolicy in the rotatePolicy of the writer
writer.sample.rotatePolicy=nablarch.core.log.basic.DateRotatePolicy
# Update time. option.
writer.sample.rotateTime=12:00

7.1.4.1. Add LogWriter¶

When adding a new LogWriter, create a class that implements the LogWriter interface. When creating a LogWriter that uses LogFormatter , create by providing common processing, inheriting LogWriterSupport.

7.1.4.2. Add LogFormatter¶

hen adding a new LogFormatter, create a class that implements the LogFormatter interface. To enable changing the text that indicates the log level in the configuration, use LogLevelLabelProvider .

Along with the addition of a new LogFormatter, there may be a need to increase parameters specified during log output, and receive the parameters increased by LogFormatter. To increase the parameters specified during log output in this function, object types with variable length argument options are provided in the log output method of Logger interface.

// Logger # logInfo method signature
public void logInfo(String message, Object... options)
public void logInfo(String message, Throwable cause, Object... options)

To increase the number of parameters for log output, specify and use the options argument.

7.1.4.3. Add log output items (placeholders)¶

BasicLogFormatter uses the LogItem interface to get all the output items corresponding to each placeholder. Therefore, if a new placeholder is to be added, create the following classes.

• Create a class that implements LogItem .
• Create a class that inherits BasicLogFormatter and add a placeholder.

An example of change to acquire the boot process from the LogFormatter configuration is shown. The configuration of LogFormatter assumes the following.

# Specifies a custom LogFormatter.
writer.appLog.formatter.className=nablarch.core.log.basic.CustomLogFormatter

# Specify the format
writer.appLog.formatter.format=$date$ -$logLevel$- $loggerName$ [$bootProcess$] $message$

# Specifies the boot process in the LogFormatter configuration.
# Outputs the boot process specified here to $bootProcess$.
writer.appLog.formatter.bootProcess=CUSTOM_PROCESS

Create a class that implements LogItem .

// Class to get a custom boot process.
public class CustomBootProcessItem implements LogItem<LogContext> {

    private String bootProcess;

    public CustomBootProcessItem(ObjectSettings settings) {
        // Get the boot process from LogFormatter configuration.
        bootProcess = settings.getProp("bootProcess");
    }

    @Override
    public String get(LogContext context) {
        // Return the boot process obtained from the configuration.
        return bootProcess;
    }
}

Create a class that inherits BasicLogFormatter and add a placeholder

public class CustomLogFormatter extends BasicLogFormatter {

    // Override the method to get the log output items to be formatted.
    @Override
    protected Map<String, LogItem<LogContext>> getLogItems(ObjectSettings settings) {

        // Overwrite the placeholder of the boot process.
        Map<String, LogItem<LogContext>> logItems = super.getLogItems(settings);
        logItems.put("$bootProcess$", new CustomBootProcessItem(settings));
        return logItems;
    }
}

7.1.4.4. Do not output the log initialization message¶

An initialization message is output by this function to the log when each logger is initialized. If the initialization message is not required for the monitored log, etc, then support by creating a Writer that does not output the initialization message based on the Writer provided by this function.

If the log Adapter is used for the purpose of unifying the logger with the web application server or OSS product, this support is not necessary as initialization messages are not output.

The corresponding example shown below.

1. Import (copy) the source code of the Writer class that will be the base to the project. For example, when the log is output to a the file, copy FileLogWriter .

2. Delete the part that outputs the initialization log.

   In the case of FileLogWriter , delete the part that outputs the initialization message as shown in the modification example given below.

   private void initializeWriter() {
     try {
       out = new BufferedOutputStream(new FileOutputStream(filePath, true), outputBufferSize);
       currentFileSize = new File(filePath).length();
   
       // Delete the output process of the initialization message that was performed here
   
     } catch (IOException e) {
       throw new IllegalArgumentException(String.format("failed to create %s. file name = [%s], encoding = [%s], buffer size =[%s]",
           Writer.class.getName(), filePath, charset.displayName(), outputBufferSize), e);
     }
   }
   

3. Change such that the initialization message after the log function initialization is not output.

Override needsToWrite , and change such that the initialization message that is called the first time is not output.

/** Define the flag for initial determination */
private boolean suppressionWriting = true;

@Override
public boolean needsToWrite(final LogContext context) {
  final String message = context.getMessage();
  if (suppressionWriting) {
    //  Since it is an initialization message if the log to be output starts from "initialized.",
    // "false" is returned indicating that it is not the output target.
    if (StringUtil.hasValue(message) && message.startsWith("initialized.")) {
      suppressionWriting = false;
      return false;
    }
  }
  return super.needsToWrite(context);
}

4. Configure the created class in log.properties.

Configure the class name of the writer created in the project side, in log.properties.

The configuration example shown below.

writerNames=sample

# Configure the class created in the class name of the writer
# Configuration example when the fully qualified class name is "sample.CustomFileLogWriter"
writer.sample.className = sample.CustomFileLogWriter

7.1.5.1. Change the formatter used in LogWriter to JsonLogFormatter¶

By changing the formatter used in LogWriter to JsonLogFormatter the log output can be in JSON format.

How to use

An example of JsonLogFormatter configuration is shown below.

# To output logs in JSON format, specify JsonLogFormatter.
writer.appLog.formatter.className=nablarch.core.log.basic.JsonLogFormatter

# Specifies the output items.
writer.appLog.formatter.targets=date,logLevel,message,information,stackTrace

# Specifies the pattern used to format the date and time.
# If not specified, it will be "yyyy-MM-dd HH:mm:ss.SSS".
writer.appLog.formatter.datePattern=yyyy-MM-dd'T'HH:mm:ss.SSS'Z'

In JsonLogFormatter, the targets property specifies the output items separated by commas. The available output items are as follows. By default, all items are output.

Output items that can be specified with the targets property¶

Output items	Description
date	The date and time at which this log output was requested.
logLevel	Log level for this log output.
loggerName	The name of the logger configuration to which this log output corresponds.
runtimeLoggerName	The name specified for obtaining the logger from LoggerManager at runtime.
bootProcess	A name that identifies the boot process.
processingSystem	A name that identifies the processing architecture.
requestId	Request ID at the time this log output was requested.
executionId	The execution ID at the time this log output was requested.
userId	User ID of the logged-in user at the time this log output is requested.
message	Messages in this log output.
stackTrace	Stack trace of the exception object specified in the error information.
payload	The object specified in the option information.

Tip

The datePattern and label (log-level label) work the same way as BasicLogFormatter.

Example of the description

// Get logger by specifying a class.
// Logger is stored in class variable.
private static final Logger LOGGER = LoggerManager.get(UserManager.class);

LOGGER.logInfo("hello");

(Output result)

{"date":"2021-02-04 12:34:56.789","logLevel":"INFO","message":"hello"}

Add your own items

When payload is included in the output target, the Map<String, Object> object specified in the option information is output as a JSON object. The rules for converting objects are as follows.

Outputable objects¶

Java classes that can be output	Output by JSON
String	Output as a JSON string.
Number and its subclasses （ Integer , Long , Short , Byte , Float , Double , BigDecimal , BigInteger , AtomicInteger , AtomicLong ）	Outputs the return value of the toString() method as a JSON number. NaN and infinity are output as JSON strings.
Boolean	Output as JSON truth value (true / false).
Date Calendar and its subclasses LocalDateTime (Java 8 or later)	Output as a JSON string. The default format is "yyyy-MM-dd HH:mm:ss.SSS". To change the format, specify it with the datePattern property.
Implementation class for Map.	Output as a JSON object. If the key is not a String, or if the value is null, the output will not include the key. If you want to output null as the value, set the property ignoreNullValueMember to false.
Implementation class for List. And arrays.	Output as an array of JSON.
null	Output as null in JSON. If the value of Map is null, it is excluded from the output by default.
Other objects	Outputs the return value of the toString() method as a JSON string.

Example of the description

Map<String, Object> structuredArgs = new HashTable<String, Object>();
structuredArgs.put("key1", "value1");
structuredArgs.put("key2", 123);
structuredArgs.put("key3", true);
structuredArgs.put("key4", null);
structuredArgs.put("key5", new Date());
LOGGER.logInfo("addition fields", structuredArgs);

(Output result)

{"date":"2021-02-04 12:34:56.789","logLevel":"INFO","message":"addition fields","key1":"value1","key2":123,"key3":true,"key5":"2021-02-04 12:34:56.789"}

Tip

When using JsonLogFormatter, do not set option information other than Map < String, Object >. You can specify multiple Map objects, but if the keys overlap, only one is output and the others are ignored.

7.1.5.2. Replace the formatter used in various logs with one for JSON logs¶

The various logs are formatted in a separate way for the message part. By replacing the formatter used for each format with a formatter for JSON, the contents output by the various logs can also be output as JSON logs.

For the specific settings of each formatter, refer to the each links in the table below.

JSON version formatter for various logs¶

Log type	Supported formatters
Failure log	FailureJsonLogFormatter
SQL log	SqlJsonLogFormatter
Performance log	PerformanceJsonLogFormatter
HTTP access log	HttpAccessJsonLogFormatter
HTTP access log (for RESTful web service)	JaxRsAccessJsonLogFormatter
Messaging log	MessagingJsonLogFormatter

7.1.5.3. Set the log output by Nablarch batch to JSON format¶

To make the log output by Nablarch batch in JSON format, you need to make the following modifications in addition to the formatter settings described above.

• Switch ApplicationSettingLogFormatter for JSON.
• Switch LauncherLogFormatter for JSON
• Switch CommitLogger for JSON

Each of these settings is explained below.