Logging

The Connect2id server uses the popular Log4j 2 framework for logging. The messages can be output to a variety of destinations, such as a local text file, the console, a database or a service. Reconfiguration on the fly is possible.

The Connect2id server has a web.xml context parameter log4jConfiguration instructing Log4j to look for its configuration file in the following location:

WEB-INF/log4j.xml

Shipped configuration file

The Connect2id server ships with a Log4j configuration file for writing the messages to tomcat/logs/c2id-server.log. The verbosity is set by the level attribute.

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="error" name="C2idServer" packages="">
    <Appenders>
        <!-- Log file location uses Tomcat system variable, change for other web servers -->
        <RollingFile name="RollingFile"
                     fileName="${sys:catalina.home}/logs/c2id-server.log"
                     filePattern="${sys:catalina.home}/logs/c2id-server-%d{yyyy-MM-dd}-%i.log.gz">
            <PatternLayout>
                <Pattern>%d{ISO8601} %p %t %c{1} - %m%n</Pattern>
            </PatternLayout>
            <Policies>
                <TimeBasedTriggeringPolicy />
                <SizeBasedTriggeringPolicy size="250 MB"/>
            </Policies>
        </RollingFile>
    </Appenders>
    <Loggers>
        <Root level="info">
            <AppenderRef ref="RollingFile"/>
        </Root>
    </Loggers>
</Configuration>

To write the logs to the console

Sample Log4j configuration to cause the log messages to be written to stdout:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="error" name="C2idServer" packages="">
    <Appenders>
    	<Console name="STDOUT" target="SYSTEM_OUT" follow="true">
        	<PatternLayout>
                <Pattern>%d{ISO8601} %p %t %c{1} - %m%n</Pattern>
            </PatternLayout>
	    </Console>
    </Appenders>
    <Loggers>
        <Root level="info">
            <AppenderRef ref="STDOUT"/>
        </Root>
    </Loggers>
</Configuration>

To write the logs to Logstash

Logstash is a popular server for centralised aggregation and analysis of logs.

There are two ways to pipe Connect2id server logs to Logstash:

1. Utilise the included log4j2-jsonevent-layout plugin (available since Connect2id server v6.18). Its primary use is to produce JSON formatted log entries, but it also can be configured to pipe output to Logstash. Check out the plugin documentation for how to set this up.

2. Install a Logstash plugin to convert incoming log messages from Log4j to the expected format. One such plugin is logstash-log4j2 from Jurriaan Mous.

We looked at both approaches and the second one seems the best with the currently available plugins. For that we recommend the logstash-log4j2 plugin from Jurriaan Mous.

Setting up Log4j itself is just a matter of specifying a remote appender with the Logstash server host name / IP address and port number:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="error" name="C2idServer" packages="">
    <Appenders>
        <Socket name="Logstash" host="my.logstash.server.net" port="9201">
              <JSONLog4j2Layout singleLine="true"/>
        </Socket>
    </Appenders>
    <Loggers>
        <Root level="info">
            <AppenderRef ref="Logstash"/>
        </Root>
    </Loggers>
</Configuration>

Changing the logging configuration

Refer to the Log4j manual for instructions how to edit the configuration file. The supported output destinations are described in the appenders section.

Logger names

The messages are written under topics, using separate loggers, to ease scanning of events per server endpoint as well as system-wide events.

• MAIN – The main logger. Records general configuration, startup, shutdown and system messages. Note that Infinispan, JGroups and other subsystems may output messages under their own loggers.

• DISCOVERY – OpenID Connect discovery endpoint messages.

• CLIENT-REG – OAuth 2.0 / OpenID Connect client registration endpoint messages.

• AUTHZ-SESSION – OpenID Connect / OAuth 2.0 authorisation session endpoint messages (for the login and consent handler).

• DIRECT-AUTHZ – Direct authorisation endpoint messages.

• AUTHZ-STORE – Authorisation store messages.

• SESSION-STORE – Subject session store messages.

• TOKEN – OAuth 2.0 token endpoint messages.

• TOKEN-INTROSPECT – OAuth 2.0 token introspection endpoint messages.

• TOKEN-REVOKE – OAuth 2.0 token revocation endpoint messages.

• USERINFO – UserInfo endpoint messages.

• LOGOUT – Logout endpoint messages.

Don’t forget to watch the console and the catch-all log

Don’t forget to watch the console output of your web server. If you’re using Apache Tomcat its default configuration writes console messages to logs/catalina.out.

The console output may contain the following messages:

• Uncaught Java exceptions.
• Certain messages from service threads launched by Connect2id server components such as Infinispan cluster events and JGroups networking events.
• Thread dumps, if requested via system signal.