Logger Configuration

This chapter explains the configurable parameters related to the FioranoMQ Logger module (i.e., related to server logs or monitoring logs or dashboard logs) in the server.

For information on how to configure FioranoMQ Server Loggers in Offline and online mode, refer to the Configuring Logger section.

Introduction

Logging into FioranoMQ is achieved with the help of Log4J which makes it is possible to log in at runtime without modifying the application binaries. All log entries are logged at particular log levels. Each logger is given a logging level.  The various logger levels are given below.

Table 1: Log levels

These values are defined so that if given a value x, all entries logged with a value less than or equal to x will be received by the logger.

 

Figure 1: Loggers in hierarchical manner

Loggers are arranged hierarchies depicting parent-child relationships. Each element in the tree (Figure 1) has these two attributes as shown Figure 2, below:

 
Figure 2:  Edit Logger Properties dialog box

The log level parameter of the loggers can be set to any one of the values present in Table 1. The information present in the log files will depend on the value set. Some examples using the logger configurations are given below:

• If the 'Log Level' attribute of Fiorano.Services.Topics.MsgFlow.Message is set to trace 6), all the messages published to a topic along with its corresponding properties are logged.
• If the 'Log Level' attribute of Fiorano.Services.Topics.MsgFlow.Publish is set to trace (6), the life cycle of the message, in its various stages of sending,  is logged.
• If the 'Log Level' attribute of Fiorano.Services.Queues.Push.Message is set to trace (6), all messages sent to a queue along with its corresponding properties are logged.
• If the 'Log Level' attribute of Fiorano.Services.Queues.Pop is set to trace (6), the life cycle of the message, after it is pushed into the queue, is logged.
• If the 'Log Level' attribute of Fiorano.Services.Topics.MsgFlow.Message is set to trace (6), all the messages published to a topic along with its corresponding properties are logged.
• If the 'Log Level' attribute of Fiorano.Events.TopicPublisher is set to trace (6), all publisher events such as open and close are logged.
• If the 'Log Level' attribute of Fiorano.Events.QueueReceiver is set to trace (6), all receiver events such as  open and close are logged.
• If the 'Log Level' attribute of Fiorano.Services.Jmx.Operations is set to trace (6), details of all Jmx operations are logged.

If the 'Log Level' attribute of Fiorano.Services.Jmx.Attributes is set to trace ( 6), the details of all attributes accessed using Jmx connections are logged.

AppenderAdditive

AppenderAdditive specifies the Appender Additivity for the logger. The output of a log statement of logger, say C, will go to all appenders and ancestors of C. However, if an ancestor of logger C, say P, has the additivity flag set to false, then C's output will be directed to all the appenders in C as well as to all ancestors up to and including P but not to the appenders of the ancestors of P.

Valid value:

The default value for the AppenderAdditive parameter is yes

• yes - Logging output of present element will be directed to its parent.
• no - Logging output of present element will not be directed to its parent.

LogLevel

LogLevel is the level of logging. No log event will be generated for a logging statement above this level.

Valid value:

The default value for the LogLevel is -1.

Legal values: -1 to 6. (Refer to table 1, above, for more information.)

LogAppender

Presented below are the details of the parameters in Fiorano->config->LogAppender

AppenderName

The AppenderName parameter provides a unique Appender Name.

Valid value:

The default value is of the AppenderName parameteris LogAppender.

Any String

AppenderType

AppenderType is a parameter that specifies the type of appender to be used. A LogAppender type, for example, decides onthe endpoint set to receive logging information.

Valid value:

The default value for the AppenderType parameter is file.

• file - the appender in use will be a file type. Log messages will be written to a file.
• console - the appender in use will be a console type. Log messages will be written to the console.

Example:

When  logged messages qualify, or are important enough, to be displayed on the console, the AppenderType of the console will need to be changed from its file value.

LogPattern

The LogPattern parameter specifies the Log4J format for printing logs. (Please refer to Log4J documentation for more details.)

Valid value:

The default value for the LogPattern Parameter is [%d{dd/MMM/yyyy HH:mm:ss}]    %-10c{1}   %-10p %m%n

Example:

{%F, %M} %-5p [%c{1}] %m%n will print CodeFileName, MethodName when the log event is generated.

ThresholdLevel

The ThresholdLevel parameter indicates that log events logged above this ThresholdLevellog level will not be received/logged by the Appender.

Valid value:

The default value of the ThresholdLevel parameter is 10.

The range of integer values in java for the ThresholdLevel parameter are -2^32 to 2^32 -1.

Note:

• All values less than or equal to zero retrieve the same result..
• All values greater than or equal to 10 retrieve the same result.

FilterPattern

The FilterPattern is a regex based string filter pattern for filtering log events received by the Appender. Only Events which matches the filter criteria are logged.

Valid value:

The default value for the FilterPattern parameter is null.

• Any valid regex expression may be used.
• null - all strings are accepted by a null regular expression.

Example:

When only the messages that match the criteria defined by the regex are to be logged, the regular expression is to be set.

PrintTarget

The PrintTarget parameter is applicable only to console appenders and the print target can be chosen to reflect the target that the console output prints to.

Valid value:

The default value for the PrintTarget parameter is System.out.

For a value set in the PrintTarget field to have any effect the AppenderType should be set console.

• System.out - When appendertype is set to console the console output will print to the standard output stream.
• System.err - When appendertype is set to console the console output will print to the standard error output stream.

FileName

The FileName parameter is the name of the log file to which the log events are logged when the AppenderType is file.

Valid value:

The values considered valid by the FileName parameter are can be any valid filename. The default value of this parameter is server.log

When a relative path for a filename is given a log file is created in <current-profile>/run/logs/. If an absolute path for a filename is given a log file is created in its corresponding directory.

IsAppend

The IsAppend parameter option is useful only when the AppenderType is specified as a file type. When the server boots and  a log file that is specified already exists, this parameter specifies whether the log file that exists overwritten or if the log entries are appended to the existing file.

Valid value:

The default value for the IsAppend Parameter is yes

• yes - Log entries are appended to the existing log file.
• no - The existing log file is overwritten by the new entries.

MaxBackupIndex

The MaxBackupIndex parameter specifies whether the type of FileAppender used by FioranoMQ is a RollingFileAppender. The RollingFileAppender can be used to roll log files based on size. When the FileSize exceeds MaxFileSize the log file will be rolled. Rolling consists of the creation of a new log file with an incremental index appended to its filename. The MaxBackupIndex parameter helps specify the maximum number of such files to be created. Example: A 2 will have at most 3 log files. file.log, file1.log, file2.log. This parameter may be used only when the AppenderType used is file.

Valid value:

The default value for the MaxBackupIndex parameter is 9.

The range of integer values in java for the MaxBackupIndex parameter are -2^32 to 2^32 -1.

All values less than or equal to zero retrieve the same result.

Dependencies

Please refer to MaxFileSize and to AppenderType.

MaxFileSize

The MaxFileSize parameter specifies the maximum size of a log file in bytes. Once the maximum size speficied is reached the log file is rolled. (For an explanation on RollingFileAppender, refer to MaxBackupIndex.) This parameter may be used when the AppenderType is a file.

Valid value:

The default value for the MaxFileSize parameter is 5000000.

Legal values: range of int values in java. (-2^32 to 2^32 -1)

All values less than or equal to zero are as good as each other.

Dependencies

Please refer to MaxBackupIndex and to AppenderType.

MaxFilterLevel

The MaxFilterLevel parameter specifies the Maximum Filter level for log events. Events logged above the log level specified by this parameter will not be received/logged by the Appender.

Valid value:

The range of integer values considered valid for the MaxFilterLevel parameter in java are -2^32 to 2^32 -1. The default value of this parameter is 10.

All values less than or equal to zero retrieve the same result.

MinFilterLevel

The MinFilterLevel parameter specifies the Minimum Filter level for log events. Events logged below the log level specified by this parameter will not be received/logged by the Appender.

Valid value:

The range of integer values considered valid in java for the MinFilterLevel parameter are -2^32 to 2^32 -1. The default value for this parameter is 1.

All values less than or equal to retrieve the same result.

LogAppender

Monitoring > config > LogAppender

AppenderName

The AppenderName parameter; provide a unique Appender Name.

Valid value:

Any String. The default value for the AppenderName parameter is LogAppender.

AppenderType

The AppenderType parameter specifies the type of appender to be used. The LogAppender Type decides the endpoint that will receive the logging information.

Valid values:

The default value for the AppenderType is file.

• file - the appender used will be of the file type. Log messages will be written to the file.
• console - the appender used will be of the console type. Log messages will be written to the console.

Example:

Whenthe logged messages qualify or are important enough to be displayed on the console, the Appendertype to console must be changed from its default value of file.

LogPattern

The LogPattern parameter specifies the Log4J format for printing logs. (Please refer to Log4J documentation for more details.)

Valid value:

The default value of the LogPattern is [%d{dd/MMM/yyyy HH:mm:ss}]    %-10c{1}   %-10p %m%n

Example:

[{%F, %M} %-5p [%c{1}] %m%n will print CodeFileName and MethodName when the log event is generated.

ThresholdLevel

Log events logged above the ThresholdLevel parameter of the log level will not be received/logged by the Appender.

Valid values:

The range of integer values that are considered valid by the ThresholdLevel Parameter in java are -2^32 to 2^32 -1. The default value for this parameter is 10.

Note:

• All values less than or equal to zero retrieve the same result.
• All values greater than or equal to 10 retrieve the same result.

FilterPattern

The FilterPatter parameter is a regex based string filter pattern for filtering log events received by the Appender. Only events which matches the filter criteria are logged.

Valid values:

The default value for the FilterPattern is null.Values considered valid by this parameter include all valid regex expression.

Null - all strings are accepted by a null regular expression.

Example:

When only the messages that match the criteria defined by the regex are to be logged, the appropriate regular expression needs to be set.

PrintTarget

The PrintTarget parameter is applicable only to console appenders.  The print target can be chosen to reflect the target the console output is to be printed to.

Valid values:

The default value is of the PrintTarget parameter is System.out.

For this parameter to work, theAppenderType should be set to console.

• System.out - When appendertype is set to console, the console output is printed to the standard output stream.
• System.err - When appendertype is set to console, the console output is printed to the standard error output stream.

Dependencies:

AppenderType

FileName

The FileName parameter specifies the name of the log file to which the log events are logged if the AppenderType is a file.

Valid values:

The default value of the FileName is server.log

Any valid filename is considered a valid value by the FileName parameter.

If a relative path for a filename is given, the log file is created in the directory relative to the file name specified: <current-profile>/run/logs/.if an absolute path for a filename is given, the log file is created in its corresponding directory.

Dependencies:

AppenderType

IsAppend

The IsAppend parameter is used only when the AppenderType is specified as file. If the log file specified already exists, this option specifies whether this log file will be overwritten or whether the log entries will be appended.

Valid values:

The default value of the IsAppend parameter is yes.

• yes - Log entries are appended to the existing log file.
• no - The log file is overwritten by the new entries.

MaxBackupIndex

The MaxBackupIndex parameter specifies whether the type of FileAppender used by FioranoMQ is a RollingFileAppender. The RollingFileAppender can be used to roll log files based on size. When the filesize exceeds MaxFileSize the log file will be rolled. A new log file will be created which will have an incremental index appended to its filename. This parameter helps specify the maximum number of files to be created and will have at most 3 log files: file.log, file1.log, file2.log. This may be used only when the AppenderType is a file.

Valid values:

The range of integer values considered valid by this parameter in java is -2^32 to 2^32 -1. The default value of this parameter is 4.

All values less than or equal to zero retrieve the same result.

Dependencies:

MaxFileSize and AppenderType.

MaxFileSize

The MaxFileSize parameter specifies the maximum size of a log file in bytes. Once a log file reaches this size it is rolled (For an explanation on RollingFileAppender see MaxBackupIndex.) This parameter may be used only when the AppenderType is a file.

Valid values:

The range of integer values considered valid by the MaxFileSize parameter in java are -2^32 to 2^32 -1. The default value of this parameter is 1000000

All values less than or equal to zero retrieve the same results.

Dependencies:

MaxBackupIndex and AppenderType.

MaxFilterLevel

The MaxFilterLevel parameter specifies the maximum filter level for log events. Events logged above this log level will not be received/logged by the Appender.

Valid values:

The range of integer values considered valid by the MaxFilterLevel parameter in java is -2^32 to 2^32 -1. The default value for this parameter is 10.

All values less than or equal to zero retrieve the same result.

MinFilterLevel

The MinFilterLevel parameter specifies the minimum filter level for log events. Events logged below this log level will not be received/logged by the Appender.

Valid values:

The range of integer values that are considered valid by the MinFilterLevel parameter in java is -2^32 to 2^32 -1. The default value for this parameter is 1

All values less than or equal to zero retrieve the same result.

Custom Filtering for Loggers

What are Filters in Logging?

Filters allow Log Events to be evaluated to determine if or how they should be published. A Filter will be called on the 'decide()' filter method and will return a Result, which is an Enum that has one of 3 values as below:

• ACCEPT
• DENY
• NEUTRAL.

What do Filters in Logging solve?

Logging on the parent Logger can sometimes flood the logs with numerous statements, especially during heavy loads. If the need is only some specific logs for specific log events, specifically configuring every child Logger-Appender pair and their log-levels can be a cumbersome task. This also resulted in incorrect file rollovers when multiple File-Appenders of respective child Loggers tried to access the same Log file at the same time.

Solution to this problem - inducting the Log Filtering feature, where a single Appender can log events for a single Parent logger, and the irrelevant logs, not satisfying any of the Custom-Filter conditions will not be logged.

How to use the Custom Filter feature?

Appenders have to be configured to have a custom filter plugin to filter log messages according to its requirement by defining Custom-Filter class and plugging it into the concerned Appender's tag in the Configs.xml file present at <FMQ_Dir>/fmq/profiles/<profile_name>/conf.

Configuring Customed Appender Specific Filters

Customized Appender-specific Filters may be configured by following the below steps:

1. Define a Custom filter class

Filter Java Class should extend the abstract class 'fiorano.jms.log.FioranoLogFilter' which has an abstract method with the following signature:

where
the return type will be "int" of any one of the below values:

• org.apache.log4j.spi.Filter.ACCEPT
• org.apache.log4j.spi.Filter.NEUTRAL
• org.apache.log4j.spi.Filter.DENY

The method 'decide' and the argument <loggingEvent> encapsulates information about the log message, logger name, log level, thread name etc. which are necessary to take a decision either to log the message or to ignore.

Public APIs available to be used to write the conditions to accept/reject a logevent are:

getLevel()

For filtering based on Loglevel Integer[0-10],

Description: To get event's Log level
Return Type: int

getLoggerName()

For filtering based on Logger Name

Description: To get event's Logger Name

Return Type: java.lang.String

getRenderedMessage()

For filtering based on Log Message

Description: To get event's Log message

Return Type: java.lang.String

getThrowable()

For filtering based on Log's throwable

Description: To get event's throwable information

Return Type: java.lang.Throwable

Example:

Allows Log events with Logger name “Fiorano.FMQ.XYZ”, and rejects rest

Sample Filter Class ''SampleFioranoLogFilter'';

Defines a filter that accepts LogEvents with Log level '4' for Logger name "Fiorano.FMQ.Services.Administrator".

Figure 3: Sample Filter class

2. Set the Classpath

The path of the Java class files of the Custome Filters defined must be placed in the FMQ classPath (<FMQ_DIR>/fmq/bin/fmq.conf)

3. Plug the Custom Filter class to the Appender

Configure the <FMQ_Dir>/fmq/profiles/<profile_name>/conf/Configs.xml file.

Under the tag "ClassName=fiorano.jms.log.def.config.AppenderConfig", set the filter plugin: CustomFilterClassName = “<FilterClassName>”
along with other appender configurations.

Figure 4: Sample snapshot: Custom Filter class 'SampleFioranoLogFilter'

The server will instantiate an object using the fully-qualified class-name and use it as a filter while logging the messages to the respective log-appenders