Log4j Configuration

Configuration

The default Log4j configuration writes log output to 3 files:

Log file Description
mpi.log The main application log with information about the startup/shutdown process and with information about errors.
mpi-messages.log The messages log containing 3-D Secure protocol messages exchanged with the Directory Server and the ACS.
mpi-statistics.log The statistics log containing performance (i.e. timing) information and failure information.

The files can be found under $CATALINA_BASE/logs. I.e. when using the mpictl script to start an MPI node the logs can be found here: $MPI_HOME/node-<node-ID>/logs.

All files are rolled over daily using a RollingFileAppender with a TimeBasedRollingPolicy. The log output is formatted according to a conversion pattern defined using a PatternLayout.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
<?xml version="1.0" encoding="UTF-8" ?>
 
<!--
  Copyright (C) 2013 by Netcetera AG.
  All rights reserved.
 
  The copyright to the computer program(s) herein is the property of Netcetera AG, Switzerland.
  The program(s) may be used and/or copied only with the written permission of Netcetera AG or
  in accordance with the terms and conditions stipulated in the agreement/contract under which
  the program(s) have been supplied.
-->
 
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">
 
  <!--
    The appender for the MPI application log.
 
    The application log contains startup information and information about errors.
 
    The log is written to logs/mpi.log and rolled over daily.
  -->
  <appender name="MPI_APPLICATION" class="org.apache.log4j.rolling.RollingFileAppender">
    <rollingPolicy class="org.apache.log4j.rolling.TimeBasedRollingPolicy">
      <param name="FileNamePattern" value="${catalina.base}/logs/mpi.%d.log"/>
    </rollingPolicy>
    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" value="%d{yyyy-MM-dd HH:mm:ss,SSS} | %-11.11t | %-17X{mpiRequest} | %28X{xid} | %36X{sessionId} | %-5p | %-28.28c{1} | %m%n" />
    </layout>
  </appender>
 
  <!--
    The appender for the MPI message log.
 
    The message log contains 3-D Secure protocol messages exchanged with the Directory Server and the ACS.
    PANs in the logged messages are masked.
 
    The log is written to logs/mpi-messages.log and rolled over daily.
  -->
  <appender name="MPI_MESSAGE" class="org.apache.log4j.rolling.RollingFileAppender">
    <rollingPolicy class="org.apache.log4j.rolling.TimeBasedRollingPolicy">
      <param name="FileNamePattern" value="${catalina.base}/logs/mpi-messages.%d.log"/>
    </rollingPolicy>
    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" value="%d{yyyy-MM-dd HH:mm:ss,SSS} | %-11.11t | %-17X{mpiRequest} | %28X{xid} | %36X{sessionId} | %-5p | %-28.28c{1} | %m%n" />
    </layout>
  </appender>
 
  <!--
    The appender for the MPI statistics log.
 
    The statistics log contains timing and failure information.
 
    The log is written to logs/mpi-statistics.log and rolled over daily.
  -->
  <appender name="MPI_STATISTICS" class="org.apache.log4j.rolling.RollingFileAppender">
    <rollingPolicy class="org.apache.log4j.rolling.TimeBasedRollingPolicy">
      <param name="FileNamePattern" value="${catalina.base}/logs/mpi-statistics.%d.log"/>
    </rollingPolicy>
    <layout class="org.apache.log4j.PatternLayout">
      <param name="ConversionPattern" value="%d{yyyy-MM-dd HH:mm:ss,SSS} | %-11.11t | %-17X{mpiRequest} | %28X{xid} | %36X{sessionId} | %-5p | %-28.28c{1} | %m%n" />
    </layout>
  </appender>
 
  <!-- Appender for collecting transaction information needed for the dashboard statistics -->
  <appender name="TRANSACTION_STATISTICS" class="com.netcetera.mpi.business.perf4j.TransactionStatisticsAppender"/>
 
  <appender name="ASYNC_COALESCING_STATISTICS" class="org.perf4j.log4j.AsyncCoalescingStatisticsAppender">
    <!--
      The TimeSlice option is used to determine the time window for which
      all received StopWatch logs are aggregated to create a single
      GroupedTimingStatistics log. Here we set it to 60 seconds.
    -->
    <param name="TimeSlice" value="60000"/>
    <appender-ref ref="JMX_STATISTICS"/>
  </appender>
 
  <appender name="JMX_STATISTICS" class="org.perf4j.log4j.JmxAttributeStatisticsAppender">
    <param name="TagNamesToExpose"
          value="PaReqCreation.success,
                 PaReqCreation.failure,
                 PaReqCreation.InputValidation.success,
                 PaReqCreation.InputValidation.failure,
                 PaReqCreation.EnrollmentVerification.success,
                 PaReqCreation.EnrollmentVerification.failure,
                 PaReqCreation.EnrollmentVerification.ResponseValidation.success,
                 PaReqCreation.EnrollmentVerification.ResponseValidation.failure,
                 PaReqCreation.EnrollmentVerification.DsCommunication.success,
                 PaReqCreation.EnrollmentVerification.DsCommunication.failure,
                 PaReqCreation.EnrollmentVerification.ErrorNotification.success,
                 PaReqCreation.EnrollmentVerification.ErrorNotification.failure,
                 PaResValidation.success,
                 PaResValidation.failure,
                 PaResValidation.InputValidation.success,
                 PaResValidation.InputValidation.failure,
                 PaResValidation.PaResConversion.success,
                 PaResValidation.PaResConversion.failure,
                 PaResValidation.MessageElementValidation.success,
                 PaResValidation.MessageElementValidation.failure,
                 PaResValidation.SessionRetrieval.success,
                 PaResValidation.SessionRetrieval.failure,
                 PaResValidation.TimeoutValidation.success,
                 PaResValidation.TimeoutValidation.failure,
                 PaResValidation.MessageValidation.success,
                 PaResValidation.MessageValidation.failure,
                 PaResValidation.MessageValidation.ResponseValidation.success,
                 PaResValidation.MessageValidation.ResponseValidation.failure,
                 PaResValidation.MessageValidation.ErrorNotification.success,
                 PaResValidation.MessageValidation.ErrorNotification.failure,
                 PaResValidation.MessageValidation.SignatureValidation.success,
                 PaResValidation.MessageValidation.SignatureValidation.failure" />
  </appender>
 
  <logger name="com.netcetera.mpi.business.message.MessageLogger" additivity="false">
    <level value="INFO" />
    <appender-ref ref="MPI_MESSAGE" />
  </logger>
 
  <logger name="org.perf4j.TimingLogger" additivity="false">
    <level value="INFO" />
    <appender-ref ref="MPI_STATISTICS" />
    <appender-ref ref="ASYNC_COALESCING_STATISTICS" />
    <appender-ref ref="TRANSACTION_STATISTICS" />
  </logger>
 
  <root>
    <level value="INFO" />
    <appender-ref ref="MPI_APPLICATION" />
  </root>
 
</log4j:configuration>

Mapped Diagnostic Context (MDC)

The MPI application uses Mapped Diagnostic Context (MDC) to expose additional information available for log output.

The following context information is exposed:

1
2
3
4
5
6
7
8
/** The transaction ID (XID) as a Base64 encoded 20 byte value (i.e. 28 characters). */
private static final String XID         = "xid";
 
/** The MPI internal session ID. */
private static final String SESSION_ID  = "sessionId";
 
/** The type of MPI request. */
private static final String MPI_REQUEST = "mpiRequest";

The mpiRequest may take one of the following values:

1
2
3
4
5
/** Payer Authentication Request Creation. */
PA_REQ_CREATION,
 
/** Payer Authentication Response Validation. */
PA_RES_VALIDATION;

You can use information exposed via MDC in your log output by using the following conversion pattern (e.g. for mpiRequest):

%X{mpiRequest}

For more details about conversion patterns please refer to the Log4j PatternLayout documentation.

Statistics

The MPI application uses Perf4j to gather performance and failure statistics.

Refer to Perf4j Tags for an overview of the tags used with output in the statistics log.

Use your own configuration

Although not recommended, you can use your own Log4j configuration.

To do so, you have to set a system property and pass it to the MPI application on startup.

E.g. when using the mpictl script, you can start the MPI as follows to use the log4j configuration located under /etc/mpi/log4j.xml on the filesystem:

$ $MPI_HOME/bin/mpictl.sh -j '-Dlog4j.configuration=file:/etc/mpi/log4j.xml' start

If no file: prefix is given, the configuration is loaded from the classpath.