class Sawmill::Rotater

The Sawmill Rotater provides log rotation services for logfile formatting, supporting several different log rotation strategies.

The formatter implemented by Sawmill::EntryProcessor::Format already recognizes a Rotater as a supported destination, and automatically interfaces with it to ensure that log records aren’t split into multiple files by rotation.

You may also interface with a rotater manually. The core of rotater usage is the Channel, which lets you ensure that groups of log entries end up in the same log file regardless of log rotation. Generally, to use a rotater, you obtain one or more channels and write formatted entries to them, either telling them explicitly where the allowable file breaks are, or by letting the rotater break the file anywhere it wants. See the #create_channel method and the Channel object for more details.

Public Class Methods

new(io_manager_, opts_={}) click to toggle source

Create a rotater using the given rotation strategy. See Sawmill::Rotater::DateBasedLogFile and Sawmill::Rotater::ShiftingLogFile for examples of common strategies.

The rotation strategy can be passed as an object or as a class with a set of options that will be used to instantiate the strategy. In addition to those options, the following options are recognized:

:omit_directives: If true, omit standard logfile directives. Default is false.
:concurrent_writes: Set this to true if you expect multiple processes to attempt to write to the same log file simultaneously. This option causes the rotater to surround writes with an acquisition of the cooperative filesystem lock (if available) for the logfile, in an attempt to prevent lines from interleaving in one another. Default is false.
:encoding: Specify an encoding for file data. (Ruby 1.9 only). You may pass either an encoding object or an encoding name. If not specified, writes raw bytes (e.g. defaults to ASCII-8BIT).

# File lib/sawmill/rotater.rb, line 89
def initialize(io_manager_, opts_={})
  @omit_directives = opts_.delete(:omit_directives)
  @concurrent_writes = opts_.delete(:concurrent_writes)
  if SUPPORTS_ENCODING
    @encoding = opts_.delete(:encoding)
    if @encoding && !@encoding.respond_to?(:name)
      @encoding = ::Encoding.find(@encoding)
    end
  end
  if io_manager_.kind_of?(::Class)
    @io_manager = io_manager_.new(opts_)
  else
    @io_manager = io_manager_
  end
  @handles ||= {}
  @mutex ||= ::Monitor.new
end

Public Instance Methods

create_channel(opts_={}) click to toggle source

Create a new Channel for this Rotater. See Sawmill::Rotater::Channel for details on the Channel object.

The following options are recognized:

:auto_rotate: Put the channel in auto-rotate mode. In this mode, the rotater is allowed to rotate the logfile at any time for that channel. It is the equivalent of calling check_rotate on the channel after every write. Default is false.

# File lib/sawmill/rotater.rb, line 119
def create_channel(opts_={})
  Channel.new(self, opts_)
end