PingFederate Server

Logging in JSON format

PingFederate can write logs in JSON format using the jog4j2 logging library. In addition to being easily human-readable, JSON is a common logging format for security information and event management (SEIM) security tracking systems.

About this task

You can find JSON log templates in the <pf-install>/server/default/conf/log4j/json-templates directory.

PingFederate includes JSON templates for the following log files:

  • admin-api.log

  • admin-audit.log

  • admin-event-detail.log

  • console.log

  • provisioner-audit.log

  • provisioner-channel-summary.log

  • provisioner.log

  • runtime-api.log

  • server.log

  • thread-pool-exhaustion-dump.log

  • transaction.log

The following are not log4j2-enabled, so no JSON log templates are provided:

  • init.log

  • jvm-garbage-collection.log

  • request.log

The log4j2.xml file contains rolling file appenders that produce both standard and JSON formatted outputs. By default, both formats are outputted to the same filename.

If you want only one format, commment out the appender for the other format.

If you want both standard and JSON formatted logs, you should use different filenames for each format. Otherwise, both formats will be interwoven in the same file.

Steps

  1. Open the <pf-install>/pingfederate/server//default/conf/log4j2.xml file in a text editor.

  2. (Optional) For each JsonTemplateLayout value, designate the URI location of the desired JSON templates.

    The ${sys:pf.log4j.json.templates.uri} URI designates the default location where the JSON log file templates are stored.You can replace this with a custom URI filepath.Otherwise, log files are stored in their default location of <pf-install>/server/default/conf/log4j/json-templates.

  3. For each log appender, uncomment the appender-ref for the JSON format output.

  4. For each log appender, comment out the appender-ref for the non-JSON format output.Doing this will avoid PingFederate writing both JSON and rolling file formats to the same log file.

  5. Save and close the log4j2.xml file.

Custom log patterns

To support custom log patterns in log4j2 logs using JSON output format, you must use special syntax.

For example, if a log file appender references the custom HTTP header using %header to log Content-Type:

<RollingFile ... >
	<PatternLayout>
    	<pattern>%d | %header{Content-Type} | %m%n</pattern>
	</PatternLayout>
...
</RollingFile>

In the corresponding JSON template, you must refer to the %header{Content-Type} using the following JSON object:

{
  "instant": {
    "$resolver": "timestamp",
    "pattern": {
      "format": "yyyy-MM-dd'T'HH:mm:ss.SSSXX"
    }
  },
  "headerContentType": {
    "$resolver": "pattern",
    "pattern": "%header{Content-Type}"
  }
}

You can find the reference to the relevant JSON template in the log4j2.xml file. The JSON file appender names typically include a -JSON suffix. The associated eventTemplateUri value indicates the relevant JSON template name.

<RollingFile name="RuntimeApiAudit-JSON" ...>
	<JsonTemplateLayout eventTemplateUri="file://${sys:pf.conf.dir}/log4j/json-templates/runtime-api-log.json"/>
...
</RollingFile>

Creating custom JSON templates

You can customize JSON log outputs in two ways:

  • Change existing log templates to include or exclude particular event fields.

  • Create new log templates to include the event fields that you want to log.

You can include any JSON event field, as long as it is formatted in the Log4j template syntax.

Learn more about Log4j template syntax in the Log4j documentation.

You can include PingFederate-specific event fields by using the syntax in the Custom log patterns section. You can find PingFederate-specific fields in the log4j2.xml file in PatternLayout containers.

Steps

  1. In the <pf-install>/server/default/conf/log4j/json-templates directory, create a copy of the desired JSON log template file, and give the new file a relevant name.

  2. Modify the new template file with the JSON fields and formats that you want to log.

  3. Modify the log4j2.xml file to reference the new template.

    For example, if you’re modifying the JSON server log to reference a new template named server-log-custom.json, add the following to the log4j2.xml file:

    Example:

    <RollingFile name="FILE-JSON"
                 	fileName="${sys:pf.log.dir}/server.log"
                 	filePattern="${sys:pf.log.dir}/server.log.%i"
                 	ignoreExceptions="false">
        	<JsonTemplateLayout eventTemplateUri="${sys:pf.log4j.json.templates.uri}/server-log-custom.json"/>
        	...
    	</RollingFile>

  4. Ensure that the appender is referenced for use by a logger. For this example there should be am uncommented appender-ref that refers to the FILE-JSON rolling file appender where the custom JSON template is located.