Logging configuration

The Connect2id server uses the popular Log4j 2 framework for logging. Its key features:

• Automatic reconfiguration on the fly
• High-performance (5 - 10 times gain) with asynchronous output.

The Log4j configuration file is located in the WEB-INF directory of the web application:

WEB-INF/log4j.xml

Please, refer to the Log4j manual for how to edit the configuration file.

Logger names

Messages are written to 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.

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.

Shipped configuration file

The Connect2id server ships with the following Log4j configuration file:

<?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="debug">
            <AppenderRef ref="RollingFile"/>
        </Root>
    </Loggers>
</Configuration>

Piping messages to Logstash

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

There are two ways to attach Connect2id server logging to Logstash:

1. Install a Log4j plugin that converts the log messages to the JSON format expected by Logstash and deliver them to it over the network.

2. Install a Logstash plugin to convert incoming log messages from Log4j to the expected format.

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="7000">
            <SerializedLayout />
        </Socket>
    </Appenders>
    <Loggers>
        <Root level="debug">
            <AppenderRef ref="Logstash"/>
        </Root>
    </Loggers>
</Configuration>