Logging configuration (fs-logging.conf) - Log4j 2

The file fs-logging.xml is located in the FirstSpirit Server subdirectory conf and contains important configuration settings for the log outputs. It must be adapted, if necessary.

Changes to the configuration file fs-logging.xml can be carried out via FirstSpirit ServerMonitoring (see Logging). The changes are subsequently written into the configuration file and updated on the server. If access to the file system is available, fs-logging.xml can also be directly changed via the configuration file.

Occurred errors and info messages are transferred to the logging framework (e. g. “Log4j”, “Logback”). The log outputs can be categorised via the framework. The configuration example shows, e.g., the categories DEBUG, INFO and ERROR. It is, however, also possible to configure additional categories (e.g. FATAL, WARN). The two stages ALL and OFF, which either deactivate the logging completely (OFF) or output all messages unfiltered (ALL), are an exception.

Further logging files are included in the FirstSpirit scope of installation. Activation of a certain logging configuration as well as filtering and output type can be configured via ServerMonitoring during runtime (see Logging).

Configuration files should have the syntax

fs-logging.<Logevel>.xml

to ensure they are recognised by FirstSpirit and activated via ServerMonitoring.

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN" packages="de.espirit.firstspirit.server.logging">
   <Appenders>
      <!-- dated logging is used by server monitoring for log file display -->
      <FsAppender name="fs" datedLogging="true" maxFileSize="5MB" buffer="8192" flushCycle="10"/>
   </Appenders>
   <Loggers>
      <Logger name="org.eclipse.jetty" level="WARN" additivity="false">
         <AppenderRef ref="fs"/>
      </Logger>
      <Logger name="org.apache" level="WARN" additivity="false">
         <AppenderRef ref="fs"/>
      </Logger>
      <Logger name="org.apache.fontbox" level="ERROR" additivity="false">
         <AppenderRef ref="fs"/>
      </Logger>
      <Logger name="org.apache.pdfbox" level="ERROR" additivity="false">
         <AppenderRef ref="fs"/>
      </Logger>
      <Root level="INFO">
          <AppenderRef ref="fs"/>
      </Root>
   </Loggers>
</Configuration>

For further information on the logging framework “log4j 2” and a parameter description see https://logging.apache.org/log4j/2.x/manual/configuration.html

Details of paths under Windows: If a file is to be specified for output of the log files, the path must be given as follows (path details separated by /):

<File name="audit" fileName="/home/firstspirit/log/audit.log" bufferedIO="true" immediateFlush="true" append="true">

Example:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN" packages="de.espirit.firstspirit.server.logging">
   <Appenders>
      <!-- dated logging is used by server monitoring for log file display -->
      <File name="audit" fileName="/home/firstspirit/log/audit.log" bufferedIO="true" immediateFlush="true" append="true">
         <PatternLayout>
            <pattern>%d{DEFAULT} %p %C{10} [%t] %m %n</pattern>
         </PatternLayout>
      </File>
      <FsAppender name="fs" consoleLogging="false" plainLogging="true"
datedLogging="true" maxFileSize="5MB" buffer="8192" flushCycle="10"/>
   </Appenders>
   <Loggers>
      <Logger name="de.espirit.firstspirit.logging.audit" level="INFO" additivity="false">
         <AppenderRef ref="audit"/>
      </Logger>
      ...
      <Root level="INFO">
         <AppenderRef ref="fs"/>
      </Root>
   </Loggers>
</Configuration>

Parameters for selecting the logging method

The configuration parameters described below are used for selecting the logging method and can be activated/deactivated independently of each other. Permitted values are 0 for “deactive” and 1 for “active”.

consoleLogging

Toggle for log message output to the console (command line/Shell) from which FirstSpirit has been started.

plainLogging

Toggle for log message output as plain text in a file. The log file for the server always has the name fs-server.log.

datedLogging

Toggle for log message output as plain text in a file. The date of the first entry is always added to the log file name, e.g. fs-server.20070322_100436.log (with first entry on March 22, 2007 at 10:04:36 a.m.). Activate this parameter to search within the ServerMonitoring log files.

Parameters for maximum file size configuration

maxFileSize

This parameter influences the max. permitted log file size. The size is stated in Bytes. Default value is 5 MB.

Configuration of the log rotation

Depending on the logging method, a reset or rotation occurs if the max. permitted log file size has been achieved.

1. If the parameter plainLogging has been activated and the parameter datedLogging deactivated, the current log file (e.g. fs-server.log) is renamed. The date of the first entry is added (e.g. fs-server.20070322_100436.log). The renamed file is subsequently compressed and the additional suffix .gz is added to the name. Meanwhile, further logging takes place in a newly created log file with the original name.
2. If the parameter plainLogging has been deactivated and the parameter datedLogging activated, the current log file (e.g. fs-server.20070322_100436.log) is compressed and the additional suffix .gz is added to the name. Meanwhile, further logging takes place in a newly created log file (with new date extension).
3. If the parameters plainLogging and datedLogging have both been activated, logging occurs in the log files with and without date extension. Rotation occurs similar to point 2 (the log file without date extension is simply reset).

Parameters for logging behaviour configuration

buffer

Influences the buffer size (in bytes) (default value: 8192 bytes) which should be used internally. The buffer accepts log messages and stores them until the buffer size has been reached. Only then are the messages written into the log file to avoid unnecessary and time-intensive write operations. When terminating the server, it is still written into the buffer even if the buffer size has not been reached.

flushCycle

Determines the maximum time (in seconds) between two write operations. If this time has elapsed, it is still written into the buffer even if the buffer size has not been reached.

Log messages which are amongst others relevant for debugging can be found not only in the file fs-server.log but also in the file fs-wrapper.log (see Logging).

Configuration of the audit logging

The FirstSpirit logging can be enhanced by audit functions. This is documented within a separate area that can be found here: Audit logging in FirstSpirit.

Run level

When a FirstSpirit Server starts, information about the current run level is available.

The run levels are output in various locations:

• as a log output in the fs-server.log or fs-wrapper.log file
• as a value [number] in the ~FS/.fs.lock file

These run levels can indicate whether and/or when a server functionality is available:

• SHUTDOWN (run level 0)
  The server has been shut down.
  Note: The ~FS/.fs.lock file is not available in this run level.
• IN_PROGRESS (run level 20)
  The server is starting or being shut down; no functionalities are available with certainty.
• CORE_STARTED (run level 40)
  The basic functionalities are available; the server can be accessed via the SOCKET port.
• ROOT_WEBAPP_STARTED (run level 60)
  The server can now be accessed via the HTTP port as well.
• CORE_WEBAPPS_STARTED (run level 80)
  The global web applications are available.
• STARTED (run level 100)
  All FirstSpirit functionalities are available.

It is possible to respond via the API for example, in this run level (RunLevelAgent interface, de.espirit.firstspirit.agency package, FirstSpirit Access API).