JsonAuditEventHandler

Logs events as JSON objects to a set of JSON files. There is one file for each topic defined in topics, named with the format topic.audit.json.

The JsonAuditEventHandler is the preferred file-based audit event handler.

Declare the configuration in an audit service, as described in "AuditService".

Usage

{
  "type": "AuditService",
  "config": {
    "config": {},
    "eventHandlers": [
    {
      "class": "org.forgerock.audit.handlers.json.JsonAuditEventHandler",
      "config": {
        "name": configuration expression<string>,
        "topics": [ configuration expression<string>, ... ],
        "logDirectory": configuration expression<string>,
        "elasticsearchCompatible": configuration expression<boolean>,
        "fileRotation": {
          "rotationEnabled": configuration expression<boolean>,
          "maxFileSize": configuration expression<number>,
          "rotationFilePrefix": configuration expression<string>,
          "rotationFileSuffix": configuration expression<string>,
          "rotationInterval": configuration expression<duration>,
          "rotationTimes": [ configuration expression<duration>, ... ]
        },
        "fileRetention": {
          "maxNumberOfHistoryFiles": configuration expression<number>,
          "maxDiskSpaceToUse": configuration expression<number>,
          "minFreeSpaceRequired": configuration expression<number>,
          "rotationRetentionCheckInterval": configuration expression<duration>
        },
        "buffering": {
          "writeInterval": configuration expression<duration>,
          "maxSize": configuration expression<number>
        }
      }
    }]
  }
}

Configuration

"name": configuration expression<string>, required

The event handler name. This property is used only to refer to the event handler, but is not used to name the generated log file.

"topics": array of configuration expression<string>, required

An array of one or more topics that this event handler intercepts. IG can record the following audit event topics:

  • access: Log access audit events. Access audit events occur at the system boundary, and include the arrival of the initial request and departure of the final response.

    To record access audit events, configure AuditService inline in a route, or in the heap.

  • customTopic: Log custom audit events. To create a topic for a custom audit event, include a JSON schema for the topic in your IG configuration.

    To record custom audit events, configure AuditService in the heap, and refer to it from the route or subroutes.

For an example of how to set up custom audit events, see "Recording Custom Audit Events".

"logDirectory": configuration expression<string>, required

The file system directory where log files are written.

elasticsearchCompatible: configuration expression<boolean>, optional

Set to true to enable compatibility with ElasticSearch JSON format. For more information, see the ElasticSearch documentation.

Default: false

"fileRotation": object, optional

File rotation settings for log files.

The file rotation object has the following fields:

"rotationEnabled": configuration expression<boolean>, optional

Whether file rotation is enabled for log files.

Default: false.

"maxFileSize": configuration expression<number>, optional

The maximum file size of an audit log file in bytes. A setting of 0 or less indicates that the policy is disabled.

Default: 0.

"rotationFilePrefix": configuration expression<string>, optional

The prefix to add to a log file on rotation.

This has an effect when time-based file rotation is enabled.

"rotationFileSuffix": configuration expression<string>, optional

The suffix to add to a log file on rotation, possibly expressed in SimpleDateFormat.

This has an effect when time-based file rotation is enabled.

Default: -yyyy.MM.dd-HH.mm.ss, where yyyy characters are replaced with the year, MM characters are replaced with the month, dd characters are replaced with the day, HH characters are replaced with the hour (00-23), mm characters are replaced with the minute (00-60), and ss characters are replaced with the second (00-60).

"rotationInterval": configuration expression<duration>, optional

The time interval after which to rotate log files. This duration must not be zero.

This has the effect of enabling time-based file rotation.

For information about supported formats for duration, see duration.

"rotationTimes": array of configuration expression<duration>, optional

The durations, counting from midnight, after which to rotate files.

The following example schedules rotation six and twelve hours after midnight: 

"rotationTimes": [ "6 hours", "12 hours" ]

This has the effect of enabling time-based file rotation.

For information about supported formats for duration, see duration.

"fileRetention": object, optional

File retention settings for log files.

The file retention object has the following fields:

"maxNumberOfHistoryFiles": configuration expression<number>, optional

The maximum number of historical audit files that can be stored. If the number exceeds this maximum, older files are deleted. A value of -1 disables purging of old log files.

Default: 0.

"maxDiskSpaceToUse": configuration expression<number>, optional

The maximum disk space in bytes that can be used for audit files. If the audit files use more than this space, older files are deleted. A negative or zero value indicates that this policy is disabled, and historical audit files can use unlimited disk space.

"minFreeSpaceRequired": configuration expression<string>, optional

The minimum free disk space in bytes required on the system that houses the audit files. If the free space drops below this minimum, older files are deleted. A negative or zero value indicates that this policy is disabled, and no minimum space requirements apply.

"rotationRetentionCheckInterval": configuration expression<string>, optional

Interval at which to periodically check file rotation and retention policies. The interval must be a duration, for example, 5 seconds, 5 minutes, or 5 hours.

"buffering": object, optional

Settings for buffering events and batch writes.

"writeInterval": configuration expression<duration>, optional

The interval at which to send buffered event messages. If buffering is enabled, this interval must be greater than 0.

Default: 1 second

For information about supported formats for duration, see duration.

"maxSize": configuration expression<number>, optional

The maximum number of event messages in the queue of buffered event messages.

Default: 10000

Example

In the following example, a JSON audit event handler logs audit events for access. For an example of setting up and testing this configuration, see "Recording Access Audit Events in JSON". 

{
  "name": "30-json",
  "baseURI": "http://app.example.com:8081",
  "condition": "${matches(request.uri.path, '^/home/json-audit')}",
  "heap": [
    {
      "name": "AuditService",
      "type": "AuditService",
      "config": {
        "eventHandlers": [
          {
            "class": "org.forgerock.audit.handlers.json.JsonAuditEventHandler",
            "config": {
              "name": "json",
              "logDirectory": "/tmp/logs",
              "topics": [
                "access"
              ],
              "fileRetention": {
                "rotationRetentionCheckInterval": "1 minute"
              },
              "buffering": {
                "maxSize": 100000,
                "writeInterval": "100 ms"
              }
            }
          }
        ]
      }
    }
  ],
  "auditService": "AuditService",
  "handler": "ReverseProxyHandler"
}
Read a different version of :