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>

File retention

Automatic file retention for log files will not be performed by default. 

The following example is configured to remove server.log.yyyy-MM-dd files that are older than 60 days.

<DefaultRolloverStrategy>
  <Delete basePath="logs" maxDepth="2">
    <IfFileName glob="server.*.log" />
    <IfLastModified age="60d" />
  </Delete>
</DefaultRolloverStrategy>
Click to copy

A complete example:

<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>
     <DefaultRolloverStrategy>
     	<Delete basePath="logs" maxDepth="2">
     		<IfFileName glob="server.*.log" />
     		<IfLastModified age="60d" />
     	</Delete>
     </DefaultRolloverStrategy>
</RollingFile>
Click to copy

Send events to syslog

<Appenders>

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

</Appenders>

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.

NOTE: Depending on the environment, parameters "format" and "appName" might need to be added to get trace_id (available from version 4.x and later) in the communication to SYSLOG.
Example:

<Syslog name="SYSLOG" format="RFC5424" appName="PhenixID PAS" host="10.0.0.212" port="514" facility="LOCAL7" protocol="UDP"/>
Click to copy

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 ITEM set for troubleshooting

It might be sufficient to only get an output of the current ITEM set, which would be the same as the pipe output. This would minimize log output when troubleshooting.

<AsyncLogger name="com.phenixidentity.pipes.PipesVerticle" level="DEBUG"/>
Click to copy

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>
Click to copy

Pipes

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

HTTP Authentication

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

NEOTP

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

SAML

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

SAML IdP

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

BankID

<asyncLogger name="com.phenixidentity.authentication.handler.internal.BankID" level="DEBUG"/>
Click to copy

Remove logging for specific packages

Open SAML XML errors

<asyncLogger name="org.opensaml.xml" level="OFF"/>
Click to copy