Correlating log events using attributes

You can use log attributes to correlate runtime HTTP request events in runtime-request.log, runtime transactions in audit.log, and server activities in server.log.

Correlating log events makes it easier to debug and trace the cause of runtime errors.

You can use the following log attributes to correlate events in runtime-request.log, audit.log, and server.log:

%{trackingid}attr: The unique ID for a user’s session.
%{transactionid}attr: The unique ID for a single sign-on (SSO) or single logout (SLO) transaction.
%{httprequestid}attr: The unique ID for an HTTP request.

The server.log file has only trackingid enabed by default. You can add transactionid and httprequestid log attributes to the <pattern> attribute.

Steps

Open the <pingfed-install>/bin/run.properties file.
Add one or more log attributes to the jetty.runtime.requestlog.format parameter.
Save and close the file.
Open the <pingfed-install>/pingfederate/server/default/conf/log4j2.xml file.
Find the file appenders for the server.log and audit.log files.
- The server.log appender is located under RollingFile name="FILE".
- The audit.log appender is located under RollingFile name="SecurityAudit2File".
  
  If you output your logs to a JSON file, you can add any of the previous log attributes to the respective log file’s JSON log template.
  
  Learn more in Logging in JSON format.
Make sure the identifiers you added to the run.properties file are included in the output pattern.
Save and close the file.
Restart PingFederate.
If you’re running PingFederate in a clustered environment, copy the updated log4j2.xml file and jetty.runtime.requestlog.format parameter to each node.

Don’t copy the entire run.properties file to other nodes, as that file contains node-specific settings.

Example

If you want to correlate user sessions by trackingid across the runtime-request.log, audit.log, and server.log, you’d make the following changes:

In the run.properties file, add the trackingid log attribute.

jetty.runtime.requestlog.format=%{client}a - %u "%r" %s %O %{trackingid}attr

In the log4j2.xml file, ensure the trackingid log attribute is present in the log pattern of the log files to which you want to correlate.

    <RollingFile name="SecurityAudit2File"
                 	fileName="${sys:pf.log.dir}/audit.log"
                 	filePattern="${sys:pf.log.dir}/audit.%d{yyyy-MM-dd}.log"
                 	ignoreExceptions="false">
        	<PatternLayout>
            	<!-- Uncomment this if you want to use UTF-8 encoding instead of system's default encoding. -->
            	<!-- <charset>UTF-8</charset> -->
                <!--
                ...
                -->
                <pattern>%d| %X{trackingid}| %X{transactionid}| %X{event}| %X{subject}| %X{ip} | %X{app}| %X{connectionid}| %X{protocol}| %X{host}| %X{role}| %X{status}| %X{adapterid}| %X{description}| %X{responsetime} %n</pattern>

    <RollingFile name="FILE"
                 	fileName="${sys:pf.log.dir}/server.log"
                 	filePattern="${sys:pf.log.dir}/server.log.%i"
                 	ignoreExceptions="false">
            <PatternLayout>
            	<!-- Uncomment this if you want to use UTF-8 encoding instead of system's default encoding. -->
            	<!-- <charset>UTF-8</charset> -->
            	<pattern>%d %X{trackingid} %-5p [%c] %m%n</pattern>

PingFederate Server

Correlating log events using attributes

Steps

Example