ball_logfilecleanerutil.h

Go to the documentation of this file.

/// @file ball_logfilecleanerutil.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// ball_logfilecleanerutil.h                                          -*-C++-*-
#ifndef INCLUDED_BALL_LOGFILECLEANERUTIL
#define INCLUDED_BALL_LOGFILECLEANERUTIL
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup ball_logfilecleanerutil ball_logfilecleanerutil
/// @brief  Provide a utility class for removing log files.
/// @addtogroup bal
/// @{
/// @addtogroup ball
/// @{
/// @addtogroup ball_logfilecleanerutil
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#ball_logfilecleanerutil-purpose"> Purpose</a>
/// * <a href="#ball_logfilecleanerutil-classes"> Classes </a>
/// * <a href="#ball_logfilecleanerutil-description"> Description </a>
///   * <a href="#ball_logfilecleanerutil-log-filename-pattern"> Log Filename Pattern </a>
///   * <a href="#ball_logfilecleanerutil-log-filename-pattern-conversion-rules"> Log Filename Pattern Conversion Rules </a>
///   * <a href="#ball_logfilecleanerutil-usage"> Usage </a>
///     * <a href="#ball_logfilecleanerutil-example-1-basic-usage"> Example 1: Basic Usage </a>
///     * <a href="#ball_logfilecleanerutil-example-2-cleaning-log-files-on-file-rotation"> Example 2: Cleaning Log Files On File Rotation </a>
///
/// # Purpose {#ball_logfilecleanerutil-purpose}
/// Provide a utility class for removing log files.
///
/// # Classes {#ball_logfilecleanerutil-classes}
///
/// -  ball::LogFileCleanerUtil: utility class for removing log files
///
/// @see  ball_fileobserver2, balb_filecleanerconfiguration
///
/// # Description {#ball_logfilecleanerutil-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 {#ball_logfilecleanerutil-log-filename-pattern}
///
///
/// The `ball` file observers allow the use of `%`-escape sequences to specify
/// log filenames.  The recognized sequences are as follows:
/// @code
/// %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
/// @endcode
///
/// ## Log Filename Pattern Conversion Rules {#ball_logfilecleanerutil-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.)
///
/// @code
/// -------------------+---------------
///  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*"
/// -------------------+---------------
/// @endcode
///
/// ## Usage {#ball_logfilecleanerutil-usage}
///
///
/// This section illustrates intended use of this component.
///
/// ### Example 1: Basic Usage {#ball_logfilecleanerutil-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 @ref ball_fileobserver2 ) with the following log
/// pattern:
/// @code
/// const char *appLogPattern = "/var/log/myApp/log%T";
/// @endcode
/// First, we need to convert the log filename pattern to the pattern that can
/// be used for filename matching on the filesystem:
/// @code
/// bsl::string fileNamePattern;
/// ball::LogFileCleanerUtil::logPatternToFilePattern(&fileNamePattern,
///                                                   appLogPattern);
/// @endcode
/// Finally, we test the resulting file pattern:
/// @code
/// assert("/var/log/myApp/log*" == fileNamePattern);
/// @endcode
/// ### Example 2: Cleaning Log Files On File Rotation {#ball_logfilecleanerutil-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 @ref ball_fileobserver2 ) with the following log pattern:
/// @code
/// const char *appLogPattern = "/var/log/myApp/log%T";
/// @endcode
/// First, we need to convert the log filename pattern to the pattern that can
/// be used for filename matching on the filesystem:
/// @code
/// bsl::string fileNamePattern;
/// ball::LogFileCleanerUtil::logPatternToFilePattern(&fileNamePattern,
///                                                   appLogPattern);
/// @endcode
/// 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:
/// @code
/// balb::FileCleanerConfiguration config(
///              fileNamePattern.c_str(),
///              bsls::TimeInterval(7 * bdlt::TimeUnitRatio::k_SECONDS_PER_DAY),
///              4);
/// @endcode
/// Next, we create a file observer and enable file logging:
/// @code
/// ball::FileObserver2 observer;
/// observer.enableFileLogging(appLogPattern);
/// @endcode
/// Finally, we use the utility function to install the file rotation callback
/// that will invoke file cleanup with the specified configuration:
/// @code
/// ball::LogFileCleanerUtil::enableLogFileCleanup(&observer, config);
/// @endcode
/// 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.
/// @}
/** @} */
/** @} */
 
/** @addtogroup bal
 * @{
 */
/** @addtogroup ball
 * @{
 */
/** @addtogroup ball_logfilecleanerutil
 * @{
 */
 
#include <balscm_version.h>
 
#include <balb_filecleanerconfiguration.h>
#include <balb_filecleanerutil.h>
 
#include <bdlf_bind.h>
#include <bdlf_placeholder.h>
 
#include <bsl_string.h>
 
 
namespace ball {
 
                           // =========================
                           // struct LogFileCleanerUtil
                           // =========================
 
/// This utility class provides functions for converting log file patterns
/// and for cleaning up log files based on a configuration.
///
/// See @ref ball_logfilecleanerutil 
struct LogFileCleanerUtil {
  private:
    // PRIVATE CLASS METHODS
                        // ** default callback function **
 
    /// Immediately call `balb::FileCleanerUtil::removeFiles` with the
    /// specified `config`.
    static
    void logFileCleanupOnRotationDefault(
                                 int,
                                 const bsl::string&,
                                 const balb::FileCleanerConfiguration& config);
 
  public:
    // CLASS METHODS
 
    /// Immediately call `balb::FileCleanerUtil::removeFiles` with the
    /// specified `config` and then install an
    /// `t_OBSERVER::OnFileRotationCallback` function into the specified
    /// `observer` that invokes `removeFiles` synchronously on every log
    /// file rotation.  The (template parameter) `t_OBSERVER` type must
    /// provide concrete implementation of the `ball::Observer` protocol,
    /// have a `setOnFileRotationCallback` method (see @ref ball_fileobserver ,
    /// @ref ball_fileobserver2 , and @ref ball_asyncfileobserver ), and define an
    /// `OnFileRotationCallback` type alias.  This method overrides the file
    /// rotation callback currently installed in the observer (if any).
    template <class t_OBSERVER>
    static
    void enableLogFileCleanup(
                               t_OBSERVER                            *observer,
                               const balb::FileCleanerConfiguration&  config);
 
    /// Substitute all occurrences of valid `%`-escape sequences in the
    /// specified `logPattern` with `*` and load the specified `filePattern`
    /// with the resulting string.  This utility function converts the log
    /// patterns used by various file observers and supplied to their
    /// `enableFileLogging` method (see @ref ball_fileobserver ,
    /// @ref ball_fileobserver2 , and @ref ball_asyncfileobserver ) to the file
    /// pattern used by various utility functions to find the related
    /// file(s) on the filesystem (see @ref balb_filecleanerutil  and
    /// @ref balb_filecleanerconfiguration ).
    static
    void logPatternToFilePattern(bsl::string             *filePattern,
                                 const bsl::string_view&  logPattern);
};
 
// ============================================================================
//                            INLINE DEFINITIONS
// ============================================================================
 
                           // -------------------------
                           // struct LogFileCleanerUtil
                           // -------------------------
 
// CLASS METHOD
template <class t_OBSERVER>
inline
void LogFileCleanerUtil::enableLogFileCleanup(
                               t_OBSERVER                            *observer,
                               const balb::FileCleanerConfiguration&  config)
{
    balb::FileCleanerUtil::removeFiles(config);
 
    typename t_OBSERVER::OnFileRotationCallback  rotationCallback =
        bdlf::BindUtil::bind(&logFileCleanupOnRotationDefault,
                             bdlf::PlaceHolders::_1,
                             bdlf::PlaceHolders::_2,
                             config);
 
    observer->setOnFileRotationCallback(rotationCallback);
}
 
}  // close package namespace
 
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2017 Bloomberg Finance L.P.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------------------- END-OF-FILE ----------------------------------
 
/** @} */
/** @} */
/** @} */