Edit log settings

This document describes logging in PhenixID Server, version 2.6 and later.

The reader of this document should have some basic knowledge about PhenixID Server.

Note that changes are reloaded without the requirement of restating the server.

System requirements

PhenixID Server installed.

Overview

When PhenixID server starts, by default three log-files are created:

  • server.log (see description below)
  • events.log (see description below)
  • nohup.out (Linux)/startup.log (Windows)

The logging behaviour for the files server.log and events.log can be changed if desired. This document will explain the log settings.

PhenixID server uses log4j 2 as logging API. (See documentation

Default log behaviour in PhenixID server is configured in the log4j2.xml file which is located in the PhenixID/config folder, e.g. /opt/PhenixID/Server/config or c:\Program Files\PhenixID\Server\config. By default most of the log-levels are set to INFO, but there are some that are set to WARN

Log Appenders

Log appenders describes how and where the logs will be written. There are different types of appenders available, for example console, file and syslog.

Log levels

INFO – The INFO level designates informational messages that highlight the progress of the application at coarse-grained level.

WARN – The WARN level designates potentially harmful situations.

ERROR – The ERROR level designates error events that might still allow the application to continue running.

DEBUG – The DEBUG Level designates fine-grained informational events that are most useful to debug an application.

TRACE – The TRACE Level designates finer-grained informational events than the DEBUG

server.log

The Server Log contains system information used when troubleshooting.

The default behaviour is to roll the log file every day, as in the example below:

<RollingFile
        name="FILE"
        fileName="logs/server.log"
        filePattern="logs/server.%date{yyyy-MM-dd}.log"
        append="true">
     <PatternLayout pattern="%d [%c{1}]  %p: %m%n"/>
     <Policies>
        <TimeBasedTriggeringPolicy interval="1"/>
     </Policies>
</RollingFile>

To change the default behaviour, and instead roll the log depending on size, follow the example below:

<RollingFile
        name="mynewappender"
        fileName="logs/server.log"
        filePattern="logs/server.%date{yyyy-MM-dd}.log"
        append="true">
     <PatternLayout pattern="%d [%c{1}]  %p: %m%n"/>
     <Policies>
        <TimeBasedTriggeringPolicy interval="1"/
        <SizeBasedTriggeringPolicy size="5 MB"/>
     </Policies>
     <DefaultRolloverStrategy max="10"/>
</RollingFile>

In this example each file will be 5MB and 10 files will be kept as backup.

This change can be applied to the current appender. If a new or additional appender should be used, please change the root logger element as below:

<root>
     <level value="WARN"/>
     <appender-ref ref="mynewappender"/>
</root>

events.log

The Audit Event Log contains server events like startup, deployment, user authentication and more.

The default behaviour is to roll the log file every day, as in the example below:

<RollingFile
        name="EVENT"
        fileName="logs/event.log"
        filePattern="logs/event.%date{yyyy-MM-dd}.log"
        append="true">
    <PatternLayout pattern="%d [%c{1}]  %p: %m%n"/>
    <Policies>
        <TimeBasedTriggeringPolicy interval="1"/>
    </Policies>
</RollingFile>

To change the default behaviour, and instead roll the log depending on size, follow the example below:

<RollingFile
        name="MYEVENTAppender"
        fileName="logs/event.log"
        filePattern="logs/event.%date{yyyy-MM-dd}.log"
        append="true">
    <PatternLayout pattern="%d [%c{1}]  %p: %m%n"/>
    <Policies>
        <TimeBasedTriggeringPolicy interval="1"/>
        <SizeBasedTriggeringPolicy size="5 MB"/>
    </Policies>
    <DefaultRolloverStrategy max="10"/>
</RollingFile>

In this example each file will be 5MB and 10 files will be kept as backup.

This change can be applied to the current appender. If a new or additional appender should be used, please change the logger element as below:

<Logger name="EVENT" level="INFO" additivity="false">
     <AppenderRef ref="MYEVENTAppender"/>
</Logger>

Send events to syslog

To send events to a syslog server, use configuration according to this example:

<Syslog
     name="SYSLOG"
     host="10.0.0.212"
     port="514"
     facility="LOCAL7"
     protocol="UDP"
/>

Add the appender to EVENT logger:

<Logger name="EVENT" level="INFO" additivity="false">
        <AppenderRef ref="EVENT"/>
        <AppenderRef ref="SYSLOG"/>
</Logger>

In this example, events will be sent to syslog server, as well as being written to disk.

Debug for troubleshooting

When troubleshooting it is helpful to set the log level to debug, to get additional information in the log file.

This should NOT be used in production unless specifically instructed, since the information written is substantial.

To set PhenixID server logging to debug, follow the example below:

<Loggers>
        <AsyncLogger name="com.phenixidentity" level="DEBUG"/>
        <AsyncLogger name="io.netty" level="WARN"/>
        <AsyncLogger name="com.hazelcast" level="WARN"/>
        <AsyncLogger name="org.vertx" level="WARN"/>
        <AsyncLogger name="com.orientechnologies" level="WARN"/>
        <Logger name="EVENT" level="INFO" additivity="false">
            <AppenderRef ref="EVENT"/>
        </Logger>
        <Root level="WARN">
            <AppenderRef ref="FILE"/>
        </Root>
</Loggers>

The default value for com.phenixidentity, is 'INFO'.

Debug for specific packages

It's also possible to enable debug logging for certain modules / packages.

RADIUS

<asynclogger name="com.phenixidentity.radius.authenticator" level="DEBUG"></asynclogger>

Pipes

<asynclogger name="com.phenixidentity.pipes" level="DEBUG"></asynclogger>

HTTP Authentication

<asynclogger name="com.phenixidentity.authentication" level="DEBUG"></asynclogger>

NEOTP

<asynclogger name="com.phenixidentity.neotp" level="DEBUG"></asynclogger>

SAML

<asynclogger name="com.phenixidentity.saml" level="DEBUG"></asynclogger>

SAML IdP

<asynclogger name="com.phenixidentity.samlidp" level="DEBUG"></asynclogger>