Log settings
Note
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.
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 Appender used when running standalone
When running standalone (not as a container), a log4j-appender is used to direct the logs into rolling files, as is described further below.
The appender looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<Appenders>
<Console name="CONSOLE" target="SYSTEM_OUT">
<PatternLayout pattern="%d [%c{1}] %X{trace_id} %p: %m%n" />
</Console>
<RollingFile name="FILE" fileName="logs/server.log" filePattern="logs/server.%date{yyyy-MM-dd}.log" append="true">
<PatternLayout pattern="%d [%c{1}] %X{trace_id} %p: %m%n" />
<Policies>
<TimeBasedTriggeringPolicy interval="1" />
</Policies>
</RollingFile>
<RollingFile name="EVENT" fileName="logs/event.log" filePattern="logs/event.%date{yyyy-MM-dd}.log" append="true">
<PatternLayout pattern="%d [%c{1}] %X{trace_id} %p: %m%n" />
<Policies>
<TimeBasedTriggeringPolicy interval="1" />
</Policies>
</RollingFile>
<!--
<Syslog name="SYSLOG" host="<ip or name to server>" port="<port>" facility="LOCAL7" protocol="UDP"/>
-->
</Appenders>
Log Appender used when running as a container
When running as a container, a log4j-appender is used to transform the logs into JSON Template layout. In addition to this reformatting, the logs are directed to stdout instead of files so that tools that read docker logs can be used more easily.
The appender looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<Appenders>
<Console name="CONSOLE" target="SYSTEM_OUT">
<JsonTemplateLayout eventTemplateUri="classpath:LogstashJsonEventLayoutV1.json"/>
</Console>
<Console name="FILE" target="SYSTEM_OUT">
<JsonTemplateLayout eventTemplateUri="classpath:LogstashJsonEventLayoutV1.json"/>
</Console>
<Console name="EVENT" target="SYSTEM_OUT">
<JsonTemplateLayout eventTemplateUri="classpath:LogstashJsonEventLayoutV1.json"/>
</Console>
</Appenders>
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}] %X{trace_id} %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="FILE" fileName="logs/server.log" filePattern="logs/server.%date{yyyy-MM-dd}.log" append="true">
<PatternLayout pattern="%d [%c{1}] %X{trace_id} %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.
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}] %X{trace_id} %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="EVENT" fileName="logs/event.log" filePattern="logs/event.%date{yyyy-MM-dd}.log" append="true">
<PatternLayout pattern="%d [%c{1}] %X{trace_id} %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.
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>
A complete example:
<RollingFile name="EVENT" fileName="logs/event.log" filePattern="logs/event.%date{yyyy-MM-dd}.log" append="true">
<PatternLayout pattern="%d [%c{1}] %X{trace_id} %p: %m%n"/>
<Policies>
<TimeBasedTriggeringPolicy interval="1"/>
</Policies>
<DefaultRolloverStrategy>
<Delete basePath="logs" maxDepth="2">
<IfFileName glob="server.*.log" />
<IfLastModified age="60d" />
</Delete>
</DefaultRolloverStrategy>
</RollingFile>
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 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"/>
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 and add/edit the log level for "com.phenixidentity" to "DEBUG":
<AsyncLogger name="com.phenixidentity" level="DEBUG"/>
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"/>
Debug for specific packages
It's also possible to enable debug logging for certain modules / packages, some examples:
RADIUS
<AsyncLogger name="com.phenixidentity.radius.authenticator" level="DEBUG"/>
Pipes
<AsyncLogger name="com.phenixidentity.pipes" level="DEBUG"/>
HTTP Authentication
<AsyncLogger name="com.phenixidentity.authentication" level="DEBUG"/>
NEOTP
<AsyncLogger name="com.phenixidentity.neotp" level="DEBUG"/>
SAML
<AsyncLogger name="com.phenixidentity.saml" level="DEBUG"/>
SAML IdP
<AsyncLogger name="com.phenixidentity.samlidp" level="DEBUG"/>
Remove logging for specific packages
Open SAML XML errors
<AsyncLogger name="org.opensaml.core.xml" level="OFF"/>
Control log levels via environment variable
Log levels can also be controlled via environment variables on startup, and works in the same way as modifying the name/level in the xml examples above.
This is particularly useful when running PAS as a container.
The environment variable that controls this is called PAS_LOG_LEVELS and its value should have the syntax my.package.name=MYLOGLEVEL;my.other-package.name=MYOTHERLOGLEVEL;.
So for example, if you would want to turn off OpenSAML XML logging via environment variable, it should have the value org.opensaml.core.xml=OFF;. You can include as many entries as you want, just be sure to include the ; to separate them.