Component ball_logfilecleanerutil [Package ball]

Provide a utility class for removing log files. More...

Namespaces
namespace	ball

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Log Filename Pattern
  • Log Filename Pattern Conversion Rules
  • Usage
    • Example 1: Basic Usage
    • Example 2: Cleaning Log Files On File Rotation

Purpose:

Provide a utility class for removing log files.

Classes:

ball::LogFileCleanerUtil

utility class for removing log files

See also:

Component ball_fileobserver2, Component balb_filecleanerconfiguration

Description:

This component defines a struct, ball::LogFileCleanerUtil, that provides utility functions for converting log file patterns used by ball file observers into filesystem patterns and installing a custom rotation callback into file observers to perform log file cleanup.

Log Filename Pattern:

The ball file observers allow the use of %-escape sequences to specify log filenames. The recognized sequences are as follows:

  %Y - current year (four digits with leading zeros)
  %M - current month (two digits with leading zeros)
  %D - current day (two digits with leading zeros)
  %h - current hour (two digits with leading zeros)
  %m - current minute (two digits with leading zeros)
  %s - current second (two digits with leading zeros)
  %T - current datetime, equivalent to "%Y%M%D_%h%m%s"
  %p - process Id

Log Filename Pattern Conversion Rules:

The logPatternToFilePattern conversion function does the following:

* Every recognized %-escape sequence is converted to *.

* Successive %-escape sequences without any separator between them are collapsed into a single *.

* "%%" is converted into a single %.

* All unrecognized %-escape sequences and characters are passed to output as-is.

* A single * is appended to the converted pattern when it does not terminate with *. (This is necessary for capturing rotated log files.)

  -------------------+---------------
   Log File Pattern  | File Pattern
  -------------------+---------------
   "a.log"           | "a.log*"
   "a.log.%T"        | "a.log.*"
   "a.log.%Y"        | "a.log.*"
   "a.log.%Y%M%D"    | "a.log.*"
   "a.%T.log"        | "a.*.log*"
  -------------------+---------------

Usage:

This section illustrates intended use of this component.

Example 1: Basic Usage:

The following snippets of code illustrate the basic usage of ball::LogFileCleanerUtil.

Suppose that the application was set up to do its logging using one of the ball file observers (see ball_fileobserver2) with the following log pattern:

  const char *appLogPattern = "/var/log/myApp/log%T";

First, we need to convert the log filename pattern to the pattern that can be used for filename matching on the filesystem:

  bsl::string fileNamePattern;
  ball::LogFileCleanerUtil::logPatternToFilePattern(&fileNamePattern,
                                                    appLogPattern);

Finally, we test the resulting file pattern:

  assert("/var/log/myApp/log*" == fileNamePattern);

Example 2: Cleaning Log Files On File Rotation:

The following snippets of code illustrate how the application can implement automatic log file cleanup from the observer's file rotation callback.

Suppose that the application was set up to do its logging using one of the file observers (see ball_fileobserver2) with the following log pattern:

  const char *appLogPattern = "/var/log/myApp/log%T";

First, we need to convert the log filename pattern to the pattern that can be used for filename matching on the filesystem:

  bsl::string fileNamePattern;
  ball::LogFileCleanerUtil::logPatternToFilePattern(&fileNamePattern,
                                                    appLogPattern);

Then, we create a configuration for the file cleaner utility. The sample configuration below instructs the file cleaner to remove all log files that match the specified file pattern and are older than a week, but to keep at least 4 most recent log files:

  balb::FileCleanerConfiguration config(
               fileNamePattern.c_str(),
               bsls::TimeInterval(7 * bdlt::TimeUnitRatio::k_SECONDS_PER_DAY),
               4);

Next, we create a file observer and enable file logging:

  ball::FileObserver2 observer;
  observer.enableFileLogging(appLogPattern);

Finally, we use the utility function to install the file rotation callback that will invoke file cleanup with the specified configuration:

  ball::LogFileCleanerUtil::enableLogFileCleanup(&observer, config);

Note that the file cleanup will be performed immediately and on every log file rotation performed by the file observer. Also note that this method overrides the file rotation callback currently installed in the file observer.