::Logging::Appenders::IO
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.
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'.
# File lib/logging/appenders/rolling_file.rb, line 76 76: def initialize( name, opts = {} ) 77: # raise an error if a filename was not given 78: @fn = opts.getopt(:filename, name) 79: raise ArgumentError, 'no filename was given' if @fn.nil? 80: 81: @fn = ::File.expand_path(@fn) 82: @fn_copy = @fn + '._copy_' 83: ::Logging::Appenders::File.assert_valid_logfile(@fn) 84: 85: # grab our options 86: @size = opts.getopt(:size, :as => Integer) 87: 88: code = 'def sufficiently_aged?() false end' 89: @age_fn = @fn + '.age' 90: @age_fn_mtime = nil 91: 92: case @age = opts.getopt(:age) 93: when 'daily' 94: 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 95: when 'weekly' 96: code = def sufficiently_aged? @age_fn_mtime ||= ::File.mtime(@age_fn) if (Time.now - @age_fn_mtime) > 604800 return true end false end 97: when 'monthly' 98: 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 99: when Integer, String 100: @age = Integer(@age) 101: code = def sufficiently_aged? @age_fn_mtime ||= ::File.mtime(@age_fn) if (Time.now - @age_fn_mtime) > @age return true end false end 102: end 103: 104: FileUtils.touch(@age_fn) if @age and !test(ff, @age_fn) 105: 106: meta = class << self; self end 107: meta.class_eval code, __FILE__, __LINE__ 108: 109: # we are opening the file in read/write mode so that a shared lock can 110: # be used on the file descriptor => http://pubs.opengroup.org/onlinepubs/009695399/functions/fcntl.html 111: super(name, ::File.new(@fn, 'a+'), opts) 112: 113: # setup the file roller 114: @roller = 115: case opts.getopt(:roll_by) 116: when 'number'; NumberedRoller.new(@fn, opts) 117: when 'date'; DateRoller.new(@fn, opts) 118: else 119: (@age and !@size) ? 120: DateRoller.new(@fn, opts) : 121: NumberedRoller.new(@fn, opts) 122: end 123: 124: # if the truncate flag was set to true, then roll 125: roll_now = opts.getopt(:truncate, false) 126: if roll_now 127: copy_truncate 128: @roller.roll_files 129: end 130: end
Returns the path to the logfile.
# File lib/logging/appenders/rolling_file.rb, line 168 168: def filename() @fn.dup end
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.
# File lib/logging/appenders/rolling_file.rb, line 174 174: def reopen 175: @mutex.synchronize { 176: if defined? @io and @io 177: flush 178: @io.close rescue nil 179: end 180: @io = ::File.new(@fn, 'a+') 181: } 182: super 183: self 184: end
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 193 193: def canonical_write( str ) 194: return self if @io.nil? 195: 196: @io.flock_sh { @io.syswrite(str) } 197: 198: if roll_required? 199: @io.flock? { 200: @age_fn_mtime = nil 201: copy_truncate if roll_required? 202: } 203: @roller.roll_files 204: end 205: self 206: rescue StandardError => err 207: self.level = :off 208: ::Logging.log_internal {"appender #{name.inspect} has been disabled"} 209: ::Logging.log_internal(2) {err} 210: end
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 230 230: def copy_truncate 231: return unless ::File.exist?(@fn) 232: FileUtils.concat @fn, @fn_copy 233: @io.truncate 0 234: 235: # touch the age file if needed 236: if @age 237: FileUtils.touch @age_fn 238: @age_fn_mtime = nil 239: end 240: 241: @roller.roll = true 242: end
Returns true if the log file needs to be rolled.
# File lib/logging/appenders/rolling_file.rb, line 214 214: def roll_required? 215: return false if ::File.exist?(@fn_copy) and (Time.now - ::File.mtime(@fn_copy)) < 180 216: 217: # check if max size has been exceeded 218: s = @size ? ::File.size(@fn) > @size : false 219: 220: # check if max age has been exceeded 221: a = sufficiently_aged? 222: 223: return (s || a) 224: end
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.