class Logging::Appenders::RollingFile

An appender that writes to a file and ensures that the file size or age never exceeds some user specified level.

The goal of this class is to write log messages to a file. When the file age or size exceeds a given limit then the log file is copied and then truncated. The name of the copy indicates it is an older log file.

The name of the log file is changed by inserting the age of the log file (as a single number) between the log file name and the extension. If the file has no extension then the number is appended to the filename. Here is a simple example:

/var/log/ruby.log   =>   /var/log/ruby.1.log

New log messages will continue to be appended to the same log file (`/var/log/ruby.log` in our example above). The age number for all older log files is incremented when the log file is rolled. The number of older log files to keep can be given, otherwise all the log files are kept.

The actual process of rolling all the log file names can be expensive if there are many, many older log files to process.

If you do not wish to use numbered files when rolling, you can specify the :roll_by option as 'date'. This will use a date/time stamp to differentiate the older files from one another. If you configure your rolling file appender to roll daily and ignore the file size:

/var/log/ruby.log   =>   /var/log/ruby.20091225.log

Where the date is expressed as `%Y%m%d` in the Time#strftime format.

NOTE: this class is not safe to use when log messages are written to files on NFS mounts or other remote file system. It should only be used for log files on the local file system. The exception to this is when a single process is writing to the log file; remote file systems are safe to use in this case but still not recommended.

Public Class Methods

new( name, opts ) click to toggle source

Creates a new Rolling File Appender. The name is the unique Appender name used to retrieve this appender from the Appender hash. The only required option is the filename to use for creating log files.

[:filename]  The base filename to use when constructing new log
             filenames.

The “rolling” portion of the filename can be configured via some simple pattern templates. For numbered rolling, you can use {{.%d}}

"logname{{.%d}}.log" => ["logname.log", "logname.1.log", "logname.2.log" ...]
"logname.log{{-%d}}" => ["logname.log", "logname.log-1", "logname.log-2" ...]

And for date rolling you can use `strftime` patterns:

"logname{{.%Y%m%d}}.log"            => ["logname.log, "logname.20130626.log" ...]
"logname{{.%Y-%m-%dT%H:%M:%S}}.log" => ["logname.log, "logname.2013-06-26T22:03:31.log" ...]

If the defaults suit you fine, just pass in the :roll_by option and use your normal log filename without any pattern template.

The following options are optional:

[:layout]    The Layout that will be used by this appender. The Basic
             layout will be used if none is given.
[:truncate]  When set to true any existing log files will be rolled
             immediately and a new, empty log file will be created.
[:size]      The maximum allowed size (in bytes) of a log file before
             it is rolled.
[:age]       The maximum age (in seconds) of a log file before it is
             rolled. The age can also be given as 'daily', 'weekly',
             or 'monthly'.
[:keep]      The number of rolled log files to keep.
[:roll_by]   How to name the rolled log files. This can be 'number' or
             'date'.
Calls superclass method Logging::Appenders::IO.new
# File lib/logging/appenders/rolling_file.rb, line 86
def initialize( name, opts = {} )
  @roller = Roller.new name, opts

  # grab our options
  @size = opts.fetch(:size, nil)
  @size = Integer(@size) unless @size.nil?

  @age_fn = filename + '.age'
  @age_fn_mtime = nil
  @age = opts.fetch(:age, nil)

  # create our `sufficiently_aged?` method
  build_singleton_methods
  FileUtils.touch(@age_fn) if @age && !test(?f, @age_fn)

  # we are opening the file in read/write mode so that a shared lock can
  # be used on the file descriptor => http://pubs.opengroup.org/onlinepubs/009695399/functions/fcntl.html
  @mode = encoding ? "a+:#{encoding}" : 'a+'
  super(name, ::File.new(filename, @mode), opts)

  # if the truncate flag was set to true, then roll
  roll_now = opts.fetch(:truncate, false)
  if roll_now
    copy_truncate
    @roller.roll_files
  end
end

Public Instance Methods

filename() click to toggle source

Returns the path to the logfile.

# File lib/logging/appenders/rolling_file.rb, line 115
def filename
  @roller.filename
end
reopen() click to toggle source

Reopen the connection to the underlying logging destination. If the connection is currently closed then it will be opened. If the connection is currently open then it will be closed and immediately opened.

Calls superclass method Logging::Appenders::Buffering#reopen
# File lib/logging/appenders/rolling_file.rb, line 122
def reopen
  @mutex.synchronize {
    if defined?(@io) && @io
      flush
      @io.close rescue nil
    end
    @io = ::File.new(filename, @mode)
  }
  super
  self
end

Private Instance Methods

age_fn_mtime() click to toggle source

Returns the modification time of the age file.

# File lib/logging/appenders/rolling_file.rb, line 208
def age_fn_mtime
  @age_fn_mtime ||= ::File.mtime(@age_fn)
end
build_singleton_methods() click to toggle source

We use meta-programming here to define the `sufficiently_aged?` method for the rolling appender. The `sufficiently_aged?` method is responsible for determining if the current log file is older than the rolling criteria - daily, weekly, etc.

Returns this rolling file appender instance

# File lib/logging/appenders/rolling_file.rb, line 218
def build_singleton_methods
  method =
    case @age
    when 'daily'
      -> {
        now = Time.now
        (now.day != age_fn_mtime.day) || (now - age_fn_mtime) > 86400
      }

    when 'weekly'
      -> { (Time.now - age_fn_mtime) > 604800 }

    when 'monthly'
      -> {
        now = Time.now
        (now.month != age_fn_mtime.month) || (now - age_fn_mtime) > 2678400
      }

    when Integer, String
      @age = Integer(@age)
      -> { (Time.now - age_fn_mtime) > @age }

    else
      -> { false }
    end

  self.define_singleton_method(:sufficiently_aged?, method)
end
canonical_write( str ) click to toggle source

Write the given event to the log file. The log file will be rolled if the maximum file size is exceeded or if the file is older than the maximum age.

# File lib/logging/appenders/rolling_file.rb, line 156
def canonical_write( str )
  return self if @io.nil?

  str = str.force_encoding(encoding) if encoding && str.encoding != encoding
  @io.flock_sh { @io.write str }

  if roll_required?
    @io.flock? {
      @age_fn_mtime = nil
      copy_truncate if roll_required?
    }
    @roller.roll_files
  end
  self
rescue StandardError => err
  self.level = :off
  ::Logging.log_internal {"appender #{name.inspect} has been disabled"}
  ::Logging.log_internal_error(err)
end
copy_file() click to toggle source

Returns the file name to use as the temporary copy location. We are using copy-and-truncate semantics for rolling files so that the IO file descriptor remains valid during rolling.

# File lib/logging/appenders/rolling_file.rb, line 140
def copy_file
  @roller.copy_file
end
copy_file_mtime() click to toggle source

Returns the modification time of the copy file if one exists. Otherwise returns `nil`.

# File lib/logging/appenders/rolling_file.rb, line 146
def copy_file_mtime
  return nil unless ::File.exist?(copy_file)
  ::File.mtime(copy_file)
rescue Errno::ENOENT
  nil
end
copy_truncate() click to toggle source

Copy the contents of the logfile to another file. Truncate the logfile to zero length. This method will set the roll flag so that all the current logfiles will be rolled along with the copied file.

# File lib/logging/appenders/rolling_file.rb, line 193
def copy_truncate
  return unless ::File.exist?(filename)
  FileUtils.concat filename, copy_file
  @io.truncate 0

  # touch the age file if needed
  if @age
    FileUtils.touch @age_fn
    @age_fn_mtime = nil
  end

  @roller.roll = true
end
roll_required?() click to toggle source

Returns true if the log file needs to be rolled.

# File lib/logging/appenders/rolling_file.rb, line 177
def roll_required?
  mtime = copy_file_mtime
  return false if mtime && (Time.now - mtime) < 180

  # check if max size has been exceeded
  s = @size ? ::File.size(filename) > @size : false

  # check if max age has been exceeded
  a = sufficiently_aged?

  return (s || a)
end