Log file rotation and retention
The PingDirectory server provides support for rotating log files to limit how large they can become. It also provides support for deleting old log files to limit how much total disk space can be consumed by log content.
Rotation policies
Each file-based logger can be configured with one or more rotation policies that can be used to determine when the server should rotate the active log file. When this occurs, it closes the active log file, renames it to include a timestamp indicating when it was rotated and creates a new, empty file to use for subsequent log messages.
The PingDirectory server provide support for the following log rotation policies:
-
Size-Based — Rotate log files after they reach a specified size.
-
Time Limit — Rotate log files after the active file has been in use for at least a specified length of time.
-
Filed Time — Rotate log files at fixed times of the day.
-
Never Rotate — Do not rotate the file. This should only be used in limited circumstances because it can allow log files to grow large and potentially consume all available disk space.
If a logger is configured with multiple rotation policies, then a log file can be rotated as soon as it satisfies the criteria for any of those policies. For example, if a logger is configured to rotate files after they reach 100 megabytes or after they have been active for 24 hours, then a log file can be rotated in less than 24 hours if it grows larger than 100 megabytes within that time frame. Conversely, it can be rotated before it reaches 100 megabytes in size if it does not hit that size limit within 24 hours.
Log file rotation listeners
Whenever a logger rotates its active log file, it can optionally perform additional processing on that file. This can be accomplished through a log file rotation listener. The PingDirectory server provides the following log file rotation listener implementations:
-
Copy Log File — Copies the log file to a specified alternative location.
-
Summarize — Invokes the summarize-access-log tool on the rotated log file.
You can also use the UnboundID Server SDK to create custom log file rotation listeners.
Retention policies
Retention policies are used to determine when the server should delete a log file that had previously been rotated.
The PingDirectory server supports the following retention policies:
-
File Count — Only retain a specified number of rotated log files.
-
Time Limit — Only retain rotated log files that are younger than a specified age.
-
Size Based — Only retain a specified maximum aggregate size of rotated log files.
-
Free Disk Space — Delete rotated log files if needed to maintain a specified minimum amount of free disk space.
-
Never Delete — Never delete rotated log files. This should only be used in limited circumstances because it can allow rotated log files to accumulate and potentially consume all available disk space.
If a logger is configured with multiple retention policies, then rotated log files can be deleted if the criteria associated with any of the policies is reached. For example, if a logger is configured to maintain up to twenty rotated files or up to one gigabyte of disk space, then it can retain fewer than twenty files if the aggregate space consumed by rotated log files exceeds one gigabyte. Alternatively, it can retain less than a gigabyte of rotated log files if the most recent twenty files consume less than one gigabyte of space.
When the logger needs to delete one or more files because of the retention policy, it deletes the files in chronological order based on the timestamp in the rotated file name, starting with the oldest timestamp first.