---
title: Logging in JSON format
description: 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.
component: pingfederate
version: 13.0
page_id: pingfederate:administrators_reference_guide:pf_logging_json_format
canonical_url: https://docs.pingidentity.com/pingfederate/13.0/administrators_reference_guide/pf_logging_json_format.html
revdate: November 14, 2024
section_ids:
  about-this-task: About this task
  steps: Steps
  adding-log-attributes-to-json-templates: Adding log attributes to JSON templates
  _custom_log_patterns: Adding custom log patterns
  creating-custom-json-templates: Creating custom JSON templates
  steps-2: Steps
  example: Example:
---

# 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.

## Adding log attributes to JSON templates

You can track common log events by adding log attributes to JSON templates. You can also use log attributes to correlate log events across log files.

Learn more in [Correlating log events using attributes](pf_correlating_log_events_attributes.html).

For example, if you want to correlate the `trackingid` and `transactionid` log attributes, you'd make the following changes to the appropriate JSON log template:

```json
 "transactionId": {
    "$resolver": "mdc",
    "key": "transactionid",
    "stringified": true
  },
  "trackingId": {
    "$resolver": "mdc",
    "key": "trackingid",
    "stringified": true
  },
```

## Adding 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](https://logging.apache.org/log4j/2.x/manual/json-template-layout.html#template-config).

You can include PingFederate-specific event fields by using the syntax in the [Adding custom log patterns](#_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.