Class: Logging::Appenders::RollingFile

Inherits:
IO show all
Defined in:
lib/logging/appenders/rolling_file.rb

Overview

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.

Defined Under Namespace

Classes: DateRoller, NumberedRoller

Constant Summary

Constants included from Buffering

Buffering::DEFAULT_BUFFER_SIZE

Instance Attribute Summary

Attributes inherited from IO

#close_method

Attributes included from Buffering

#auto_flushing, #buffer, #flush_period

Attributes inherited from Logging::Appender

#layout, #level, #name

Instance Method Summary collapse

Methods inherited from IO

#close

Methods included from Buffering

#close, #flush, #immediate_at=

Methods inherited from Logging::Appender

#<<, #append, #close, #closed?, #flush, #inspect

Constructor Details

#initialize(name, opts = {}) ⇒ RollingFile

call-seq:

RollingFile.new( name, opts )

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 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'.

Raises:

  • (ArgumentError) 


69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
 
# File 'lib/logging/appenders/rolling_file.rb', line 69

def initialize( name, opts = {} )
  # raise an error if a filename was not given
  @fn = opts.getopt(:filename, name)
  raise ArgumentError, 'no filename was given' if @fn.nil?

  @fn = ::File.expand_path(@fn)
  @fn_copy = @fn + '._copy_'
  ::Logging::Appenders::File.assert_valid_logfile(@fn)

  # grab our options
  @size = opts.getopt(:size, :as => Integer)

  code = 'def sufficiently_aged?() false end'
  @age_fn = @fn + '.age'
  @age_fn_mtime = nil

  case @age = opts.getopt(:age)
  when 'daily'
    code = <<-CODE
    def sufficiently_aged?
      @age_fn_mtime ||= ::File.mtime(@age_fn)
      now = Time.now
      if (now.day != @age_fn_mtime.day) or (now - @age_fn_mtime) > 86400
        return true
      end
      false
    end
    CODE
  when 'weekly'
    code = <<-CODE
    def sufficiently_aged?
      @age_fn_mtime ||= ::File.mtime(@age_fn)
      if (Time.now - @age_fn_mtime) > 604800
        return true
      end
      false
    end
    CODE
  when 'monthly'
    code = <<-CODE
    def sufficiently_aged?
      @age_fn_mtime ||= ::File.mtime(@age_fn)
      now = Time.now
      if (now.month != @age_fn_mtime.month) or (now - @age_fn_mtime) > 2678400
        return true
      end
      false
    end
    CODE
  when Integer, String
    @age = Integer(@age)
    code = <<-CODE
    def sufficiently_aged?
      @age_fn_mtime ||= ::File.mtime(@age_fn)
      if (Time.now - @age_fn_mtime) > @age
        return true
      end
      false
    end
    CODE
  end

  FileUtils.touch(@age_fn) if @age and !test(?f, @age_fn)

  meta = class << self; self end
  meta.class_eval code, __FILE__, __LINE__

  # 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
  super(name, ::File.new(@fn, 'a+'), opts)

  # setup the file roller
  @roller =
      case opts.getopt(:roll_by)
      when 'number'; NumberedRoller.new(@fn, opts)
      when 'date'; DateRoller.new(@fn, opts)
      else
        (@age and !@size) ?
            DateRoller.new(@fn, opts) :
            NumberedRoller.new(@fn, opts)
      end

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

Instance Method Details

#filename ⇒ Object

Returns the path to the logfile.



161
 
# File 'lib/logging/appenders/rolling_file.rb', line 161

def filename() @fn.dup end

#reopen ⇒ Object

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.



167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/logging/appenders/rolling_file.rb', line 167

def reopen
  @mutex.synchronize {
    if defined? @io and @io
      flush
      @io.close rescue nil
    end
    @io = ::File.new(@fn, 'a+')
  }
  super
  self
end