Error loggers

Despite their name, error loggers are not only used to report about errors. They can also provide information about significant events that occur within the server as well as warning conditions that might become a problem in the future.

Error loggers usually do not report information about operation processing unless an internal error is encountered during the course of processing an operation. Operation processing is covered by access loggers.

Each error log message has a severity that can be used to indicate how important the message is. Defined severities include:

  • Fatal Error — Critical problems that might affect the server’s ability to continue running
  • Severe Error — Significant problems that might affect the server’s functionality
  • Mild Error — Less significant and more isolated problems that might not require immediate attention
  • Severe Warning — Warnings about significant issues that might not represent errors can still require administrative action
  • Mild Warning — Warnings about less significant issues
  • Notice — Informational messages about significant events that occur within the server
  • Information — Informational messages about less significant events
  • Debug — Information that can generally only be useful when debugging low-level problems

Each logger can be configured to indicate which message severities should actually be recorded. The text-based error logger that is enabled in the out-of-the-box configuration logs messages at the following severities by default: fatal error, severe error, severe warning, and notice.

Each error log message also includes a category that is related to the server subsystem that generated it. Loggers can optionally be configured to record messages with different severities on a per-category basis.

PingDirectory Server offers several types of error loggers:

  • The text error log publisher writes messages in a structured plain-text format to files on the server filesystem. The default error logger that the server maintains is a text error log publisher. The UnboundID LDAP SDK for Java provides an API for parsing error log messages written by this log publisher.
  • The JSON error log publisher writes messages as JSON objects to files on the server filesystem. These messages are more likely to be parsable by third-party software than the format used by the text error log publisher.

  • The console JSON error log publisher writes messages as JSON objects to the server’s standard output or standard error stream. This is primarily useful for cases in which the server is running in Docker or some other type of container, and when using a framework that consumes standard output and standard error content for ingestion into a log management system.
  • The syslog error log publisher writes messages to a syslog server. This can allow log messages to be sent to a centralized system through a commonly used logging protocol.
  • The Java Database Connectivity (JDBC) error log publisher writes messages to a relational database using a specified column layout. This can also allow for centralized logging.

You can also use the UnboundID Server SDK to create custom error loggers. These can be used to customize the format of the log messages or to send log messages to other types of systems.

Access loggers

Access loggers are used to record information about interaction with clients. This includes:

  • New connections that are established
  • Connection closure and termination
  • TLS negotiation used to secure connections, including certificate chains presented by clients
  • Requests issued by clients
  • Results returned by the server, including entries and references returned for searches as well as intermediate responses returned for any operation
  • Requests that are forwarded to other servers
  • The result of any replication assurance processing that was performed
  • Entry rebalancing processing performed by PingDirectoryProxy Server to move data between backends sets

Access log messages should always include a connection ID that identifies the associated client connection. Messages that are associated with operations (those other related to connects, disconnects, and TLS negotiation) should also include an operation ID that can be used to identify all log messages associated with that operation.

Access loggers might not actually record all of these types of messages. For example, the server’s default access logger is configured to only record one message per operation when processing has completed for that operation. That message includes details about the request and result. Search result messages include the number of entries and references for that operation, but it does not record a separate message for each entry and reference that is returned.

PingDirectory Server also provides support for filtered logging. You can define fine-grained criteria to indicate which types of messages should be included in the log. This can be used to create log files that only include certain types of messages or to exclude messages that you consider unimportant.

The types of access loggers that PingDirectory Server offers include:

  • The text access log publisher writes messages in a structured plain-text format to files on the server filesystem. The default access logger that the server maintains is a text access log publisher.The UnboundID LDAP SDK for Java provides an API for parsing access log messages written by this log publisher.
  • The JSON access log publisher writes messages as JSON objects to files on the server filesystem. These messages are more likely to be parsable by third-party software than the format used by the text access log publisher.
  • The console JSON access log publisher writes messages as JSON objects to the server’s standard output or standard error stream. This is primarily useful for cases in which the server is running in Docker or some other type of container and when using a framework that consumes standard output and standard error content for ingestion into a log management system.
  • Text audit log publishers write information about changes processed by the server to files using the standard LDIF format. Audit logs can be helpful in understanding exactly what changes have been made to data in the server, and they can also be useful if you need to replay or revert changes.
  • The operation timing access log publisher is similar to the text access log publisher, but it can also include detailed information about the length of time required to process various phases of an operation. This can help identify which portions of operation processing are most expensive and might be able to help identify potential ways to improve performance.
  • The debug access log publisher is a file-based logger that writes multi-line messages with detailed information about the contents of each request received from a client and response returned by the server. It can optionally be configured to also include detailed information about access control evaluation performed in the course of processing the operation.
  • The syslog access log publisher writes messages to a syslog server. This can allow log messages to be sent to a centralized system through a commonly used logging protocol.
  • The JDBC access log publisher writes messages to a relational database using a specified column layout. This can also allow for centralized logging.
  • The admin alert access log publisher can be used to generate an administrative alert whenever the server processes an operation that matches the associated logging criteria.

The UnboundID Server SDK also provides support for creating custom access loggers if you want to use a particular log format or write log messages to other targets.

PingDirectory Server also offers the following JSON-formatted loggers:

JSON-formatted audit loggers
These complement the existing file-based audit logger in that they provide a record of changes to data in the server. Whereas the existing file-based audit logger writes information about changes as LDIF records, these loggers record information about the changes as JSON objects. There are three flavors of these JSON-formatted audit loggers:
  • One that writes to files
  • One that writes to the console (standard output or standard error)
  • One that writes to syslog
JSON-formatted HTTP operation loggers
These complement the existing HTTP operation logger in that they provide a record of all HTTP requests received by and responses sent by the server. These messages are also formatted as JSON objects, and there are file-based, console-based, and syslog-based versions.
JSON-formatted Sync loggers
These complement the existing file-based Sync logger and Sync failed operations loggers in that they provide information about the processing performed by the Synchronization Server, formatted as JSON objects. Again, these log messages can be written to files, to the console, or to syslog.

HTTP operation and trace loggers

HTTP operation loggers record information about requests and responses to HTTP-based clients. PingDirectory Server provides two types of HTTP operation loggers:

  • A file-based logger that uses the W3C common log format, which includes a timestamp, client address, the username of the requester, the HTTP request method, the request URI and optional query string, the protocol, and the status code.
  • A file-based logger that provides more detailed information about each request, which can include elements like request headers, the authorization type, cookie names, request parameters, the request content type, and the response content length.

You can also use the UnboundID Server SDK to customize HTTP operation loggers. Trace loggers are also used for recording information about processing associated with HTTP clients, but they can include content that is more specific to the type of request being processed, including OAuth token validation, SCIM, the Directory REST API, and the consent API.

PingDirectory server provides the following types of trace loggers:

  • A file-based logger that writes information in plain text format.

Sync loggers

Sync loggers provide a way to record information specific to processing performed by PingDataSync Server. Events that can trigger a sync log message include:

  • Whenever a change is detected from a source
  • Whenever a change is applied at the destination
  • Whenever an attempt to apply a change fails for some reason
  • Whenever a change is dropped or ignored (for example, because it was not needed or was outside the scope of all configured sync classes)
  • Whenever a source entry is mapped to a destination entry
  • Whenever a change is aborted during plugin processing
  • Whenever a plugin generates a custom log message

The following types of sync loggers are available:

  • A text sync log publisher that uses a multi-line plain text format to record information about PingDataSync Server processing
  • A text sync failed ops log publisher that uses a mutli-line plain text format to record more detailed information about failed synchronization processing
Note:

Both of these log publishers generate output that is intended to be read by a person. It is not optimized for automated parsing.

Debug loggers

Debug loggers provide a way to obtain detailed information about internal processing performed by the server. This can include specific informational content specifically added for low-level debugging, but at a minimum it likely includes things like any exceptions caught and handled internally during processing.

PingDirectory Server offers the following types of debug loggers:

  • A file-based debug log publisher that records messes about debug content generated within the server. These messages can span multiple lines, and they are primarily intended to be read by people rather than parsed by automated mechanisms.

Debug logging has the potential to be extremely verbose, and it might have a notable impact on performance. It should only be enabled when it is needed, and it should be limited to as small an area of the server as possible. Because optimal configuration can require detailed knowledge of server internals, debug logging should generally only be used under the direction of support personnel.

However, there is one area of debugging that can be useful without assistance from support: debugging issues with custom extensions. The UnboundID Server SDK provides support for generating debug messages within custom extensions, and PingDirectory Server includes a “Server SDK Extension Debug Logger” instance that is pre-configured to record debug messages generated by extensions created using the Server SDK.

Standard output logger

The server should only write data to standard output or standard error under very limited circumstances, like when it is specifically configured to write JSON-formatted access or error log messages to the console. However, there might be limited cases in which it could write to standard output or standard error for other purposes, or in which the underlying JVM generates messages written to those streams (for example, if you enable certain low-level JVM debugging features). In such cases, the output that would have been written to standard output or standard error should be redirected into the logs/server.out file.