About logs

Type Description

Type	Description
Access	Messages about clients accessing the server. Each message includes a datestamp, information about the connection, and information about the operation. DS servers implement access logs for HTTP and LDAP. It is possible to configure multiple access logs at the same time. Do not enable multiple unfiltered file-based access loggers for the same protocol, however. This can put significant write load on the disk subsystem for access log files, because every client request results in at least one new log message.
Audit	Records changes to directory data in LDIF. DS servers implement an audit log as a special type of file-based access log. By default, the server writes messages to `opendj/logs/audit`. For an example, refer to Enable an audit log.
Error	Messages tracing server events, error conditions, and warnings, categorized and identified by severity. By default, this is a file-based log, written to `opendj/logs/errors`. Messages have the following format: [datestamp] category=category severity=severity msgID=ID number msg=message string For lists of server messages by category, refer to Log message reference. DS error log message severity levels are: `ERROR` (highest severity) `WARNING` `NOTICE` `INFO` `DEBUG` (lowest severity) To log debug-level messages for a category of interest, refer to Debug-level logging. Use the external changelog to get notifications about changes to directory data. For details, refer to Changelog for notifications.
Server	Messages about server events since startup. This is a file-based log, written to `opendj/logs/server.out`. A `opendj/logs/server.pid` process ID file is also available when the server is running. Messages in this file have the same format as error log messages.

Access

Messages about clients accessing the server.

Each message includes a datestamp, information about the connection, and information about the operation.

DS servers implement access logs for HTTP and LDAP.

It is possible to configure multiple access logs at the same time. Do not enable multiple unfiltered file-based access loggers for the same protocol, however. This can put significant write load on the disk subsystem for access log files, because every client request results in at least one new log message.

Audit

Records changes to directory data in LDIF.

DS servers implement an audit log as a special type of file-based access log. By default, the server writes messages to opendj/logs/audit.

For an example, refer to Enable an audit log.

Error

Messages tracing server events, error conditions, and warnings, categorized and identified by severity.

By default, this is a file-based log, written to opendj/logs/errors.

Messages have the following format:

[datestamp] category=category severity=severity msgID=ID number msg=message string

For lists of server messages by category, refer to Log message reference.

DS error log message severity levels are:

ERROR (highest severity)
WARNING
NOTICE
INFO
DEBUG (lowest severity)

To log debug-level messages for a category of interest, refer to Debug-level logging.

Use the external changelog to get notifications about changes to directory data. For details, refer to Changelog for notifications.

Server

Messages about server events since startup.

This is a file-based log, written to opendj/logs/server.out. A opendj/logs/server.pid process ID file is also available when the server is running.

Messages in this file have the same format as error log messages.

You configure logging using log publishers. Log publishers determine which messages to publish, where to publish them, and what output format to use.

DS server logging supports extensibility through the ForgeRock Common Audit event framework. Common Audit deals with any event you can audit, not only the data updates recorded in a directory audit log. The ForgeRock Common Audit event framework provides log handlers for publishing to local files or to remote systems.

Common ForgeRock access logs

DS servers support the ForgeRock Common Audit event framework. The log message formats are compatible for all products using the framework. The framework uses transaction IDs to correlate requests as they traverse the platform. This makes it easier to monitor activity and to enrich reports:

The ForgeRock Common Audit event framework is built on audit event handlers. Audit event handlers can encapsulate their own configurations. Audit event handlers are the same in each product in the ForgeRock platform. You can plug in custom handlers that comply with the framework without having to upgrade the server.
The ForgeRock Common Audit event framework includes handlers for logging to local files and to external services.

Although the ForgeRock Common Audit event framework supports multiple topics, DS software currently supports handling only access events. DS software divides access events into ldap-access events and http-access events.
Common Audit transaction IDs are not recorded by default. To record transaction IDs in the access logs, configure the DS server to trust them.

Common Audit LDAP events have the following format:

{
  "eventName": "DJ-LDAP",
  "client": {
    "ip": string,                         // Client IP address
    "port": number                        // Client port number
  },
  "server": {
    "ip": string,                         // Server IP address
    "port": number                        // Server port number
  },
  "request": {                            // LDAP request
    "attrs": [ string ],                  // Requested attributes
    "authType": string,                   // Bind type such as "SIMPLE"
    "connId": number,                     // Connection ID
    "controls": [{                        // Request controls
      "control": string,                  // Control name or OID
      "critical": boolean,                // true, false
      "value": string                     // Base64-encoded
    }],
    "deleteOldRDN": boolean,              // For a modify DN request
    "dn": string,                         // Bind DN
    "filter": string,                     // Search filter
    "idToAbandon": number,                // ID to use to abandon operation
    "message": string,                    // Localized request message
    "modifications": [{                   // Attributes targeted for modification¹
      "modification": string,             // Modification type
      "attribute": string,                // Targeted attribute
      "values": [ string ]                // Modification values
    }]
    "msgId": number,                      // Message ID
    "name": string,                       // Operation name
    "newRDN": string,                     // For a modify DN request
    "newSup": string,                     // For a modify DN request
    "oid": string,                        // Operation name or OID
    "operation": string,                  // Examples: "CONNECT", "BIND", "SEARCH", "TLS"
    "opType": "sync",                     // Replication operation
    "protocol": string,                   // "LDAP", "LDAPS"
    "runAs": string,                      // Authorization ID
    "scope": string,                      // Search scope such as "sub"
    "version": string                     // Version "2", "3"
  },
  "response": {
    "additionalItems": object             // Additional information
    "controls": [{                        // Response controls
      "control": string,                  // Control name or OID
      "critical": boolean                 // true, false
    }],
    "elapsedTime": number,                // Total time queuing and processing the request
    "elapsedQueueingTime": number,        // Time the request spent waiting in the queue
    "elapsedProcessingTime": number,      // Time actively processing the request
    "elapsedTimeUnits": string,           // Time unit such as "MILLISECONDS"
    "entrySize": number,                  // Size in bytes of the largest entry
                                          // read from disk while processing
                                          // the operation
    "failureReason": string,              // Human-readable information
    "maskedMessage": string,              // Real, masked result message
    "maskedResult": string,               // Real, masked result code
    "nentries": number,                   // Number of entries returned
    "reason": string,                     // Reason for disconnect
    "status": string,                     // "SUCCESSFUL", "FAILED"
    "statusCode": string                  // For example, "0" for success
  },
  "security": {                           // Connection security, such as TLS handshake data
    "protocol": string,                   // Protocol, such as "TLSv1.3"
    "cipher": string,                     // Cipher suite
    "ssf": number                         // Security strength factor
  },
  "timestamp": string,                    // UTC date
  "transactionId": string,                // Unique ID for the transaction
  "userId": string,                       // User who requested the operation
  "_id": string                           // Unique ID for the operation
}

¹ When the advanced configuration property for the log publisher log-modified-attribute-values:true, DS logs an array of attributes targeted by modification requests. Each item indicates:

The modification type: add, delete, increment, or replace.
The attribute name.
The values for the modification, if allowed according to the log publisher configuration.

Set one of the advanced attributes exclude-values-of-attributes or include-values-of-attributes to specify which attribute values DS logs.

Common Audit HTTP events have the following format:

{
  "eventName": "DJ-HTTP",
  "client": {
    "ip": string,                         // Client IP address
    "port": number                        // Client port number
  },
  "server": {
    "ip": string,                         // Server IP address
    "port": number                        // Server port number
  },
  "http": {                               // HTTP request and response
    "request": {
      "secure": boolean,                  // HTTP: false; HTTPS: true
      "method": string,                   // Examples: "GET", "POST", "PUT"
      "path": string,                     // URL
      "queryParameters": map,             // map: { key-string: [ value-string ] }
      "cookies": map                      // map: { key-string: [ value-string ] }
    },
    "response": {
      "headers": map                      // map: { key-string: [ value-string ] }
    }
  },
  "response": {
    "detail": string,                     // Human-readable information
    "elapsedTime": number,                // Total time queuing and processing the request
    "elapsedTimeUnits": string,           // Time unit such as "MILLISECONDS"
    "status": string,                     // "SUCCESSFUL", "FAILED"
    "statusCode": string                  // For example, "0" for success
  },
  "timestamp": string,                    // UTC date
  "transactionId": string,                // Unique ID for the transaction
  "trackingIds": [ string ],              // Unique IDs from the transaction context
  "userId": string,                       // User who requested the operation
  "_id": string                           // Unique ID for the operation
}

Access log filtering

With the default access log configuration (no filtering), for every client application request, the server writes at least one message to its access log. This volume of logging gives you the information to analyze overall access patterns, or to audit access when you do not know in advance what you are looking for.

When you do know what you are looking for, log filtering lets you throttle logging to focus on what you want to read. You specify the criteria for a filtering policy, and apply the policy to a log publisher.

Log filtering policies use the following criteria:

Client IP address, bind DN, group membership
Operation type (abandon, add, bind, compare, connect, delete, disconnect, extended operation, modify, rename, search, and unbind)
Minimum entry size
Port number
Protocol used
Response time, queuing time, and processing time
Result codes (only log error results, for example)
Search response criteria (number of entries returned, unindexed search, and others)
Target DN
TLS handshakes
User DN and group membership

A log publisher’s filtering policy determines whether to include or exclude log messages that match the criteria.

Refer to the examples in Filter out administrative messages and Audit configuration changes.

Directory Services 7.4.3

About logs

Common ForgeRock access logs

Access log filtering