Current File : //opt/cpanel/ea-ruby24/root/usr/share/ri/system/Logger/cdesc-Logger.ri
U:RDoc::NormalClass[iI" Logger:ET@I" Object;To:RDoc::Markup::Document: @parts[o;;[OS:RDoc::Markup::Heading:
leveli: textI"Description;To: RDoc::Markup::BlankLine o: RDoc::Markup::Paragraph;[I"OThe Logger class provides a simple but sophisticated logging utility that ;TI"$you can use to output messages.;T@o;
;[I"RThe messages have associated levels, such as +INFO+ or +ERROR+ that indicate ;TI"Ptheir importance. You can then give the Logger a level, and only messages ;TI"-at that level or higher will be printed.;T@o;
;[I"The levels are:;T@o:RDoc::Markup::List:
@type: NOTE: @items[ o:RDoc::Markup::ListItem: @label[I"+UNKNOWN+;T;[o;
;[I"5An unknown message that should always be logged.;To;;[I" +FATAL+;T;[o;
;[I";An unhandleable error that results in a program crash.;To;;[I" +ERROR+;T;[o;
;[I""A handleable error condition.;To;;[I" +WARN+;T;[o;
;[I"A warning.;To;;[I" +INFO+;T;[o;
;[I"9Generic (useful) information about system operation.;To;;[I" +DEBUG+;T;[o;
;[I"*Low-level information for developers.;T@o;
;[
I"KFor instance, in a production system, you may have your Logger set to ;TI" +INFO+ or even +WARN+. ;TI"?When you are developing the system, however, you probably ;TI"Rwant to know about the program's internal state, and would set the Logger to ;TI"
+DEBUG+.;T@o;
;[I"K*Note*: Logger does not escape or sanitize any messages passed to it. ;TI"PDevelopers should be aware of when potentially malicious data (user-input) ;TI"Ais passed to Logger, and manually escape the untrusted data:;T@o:RDoc::Markup::Verbatim;[I".logger.info("User-input: #{input.dump}")
;TI"+logger.info("User-input: %p" % input)
;T: @format0o;
;[I"3You can use #formatter= for escaping all data.;T@o;;[
I"0original_formatter = Logger::Formatter.new
;TI"Clogger.formatter = proc { |severity, datetime, progname, msg|
;TI"G original_formatter.call(severity, datetime, progname, msg.dump)
;TI"}
;TI"logger.info(input)
;T;0S; ;
i; I" Example;T@o;
;[I"NThis creates a Logger that outputs to the standard output stream, with a ;TI"level of +WARN+:;T@o;;[I"require 'logger'
;TI"
;TI"!logger = Logger.new(STDOUT)
;TI"!logger.level = Logger::WARN
;TI"
;TI"$logger.debug("Created logger")
;TI"$logger.info("Program started")
;TI"#logger.warn("Nothing to do!")
;TI"
;TI""path = "a_non_existent_file"
;TI"
;TI" begin
;TI"$ File.foreach(path) do |line|
;TI") unless line =~ /^(\w+) = (.*)$/
;TI"? logger.error("Line in wrong format: #{line.chomp}")
;TI"
end
;TI" end
;TI"rescue => err
;TI"1 logger.fatal("Caught exception; exiting")
;TI" logger.fatal(err)
;TI" end
;T;0o;
;[I"OBecause the Logger's level is set to +WARN+, only the warning, error, and ;TI"Lfatal messages are recorded. The debug and info messages are silently ;TI"discarded.;T@S; ;
i; I"
Features;T@o;
;[ I"GThere are several interesting features that Logger provides, like ;TI"Hauto-rolling of log files, setting the format of log messages, and ;TI"Rspecifying a program name in conjunction with the message. The next section ;TI"+shows you how to achieve these things.;T@S; ;
i; I" HOWTOs;T@S; ;
i; I"How to create a logger;T@o;
;[I"LThe options below give you various choices, in more or less increasing ;TI"complexity.;T@o;;: NUMBER;[
o;;0;[o;
;[I":Create a logger which logs messages to STDERR/STDOUT.;T@o;;[I"!logger = Logger.new(STDERR)
;TI"!logger = Logger.new(STDOUT)
;T;0o;;0;[o;
;[I"?Create a logger for the file which has the specified name.;T@o;;[I"(logger = Logger.new('logfile.log')
;T;0o;;0;[o;
;[I",Create a logger for the specified file.;T@o;;[ I">file = File.open('foo.log', File::WRONLY | File::APPEND)
;TI"H# To create new (and to remove old) logfile, add File::CREAT like:
;TI"N# file = File.open('foo.log', File::WRONLY | File::APPEND | File::CREAT)
;TI" logger = Logger.new(file)
;T;0o;;0;[o;
;[I"LCreate a logger which ages the logfile once it reaches a certain size. ;TI"GLeave 10 "old" log files where each file is about 1,024,000 bytes.;T@o;;[I"1logger = Logger.new('foo.log', 10, 1024000)
;T;0o;;0;[o;
;[I"ACreate a logger which ages the logfile daily/weekly/monthly.;T@o;;[I"-logger = Logger.new('foo.log', 'daily')
;TI".logger = Logger.new('foo.log', 'weekly')
;TI"/logger = Logger.new('foo.log', 'monthly')
;T;0S; ;
i; I"How to log a message;T@o;
;[ I"ONotice the different methods (+fatal+, +error+, +info+) being used to log ;TI"Nmessages of various levels? Other methods in this family are +warn+ and ;TI"M+debug+. +add+ is used below to log a message of an arbitrary (perhaps ;TI"dynamic) level.;T@o;;;;[ o;;0;[o;
;[I"Message in a block.;T@o;;[I"2logger.fatal { "Argument 'foo' not given." }
;T;0o;;0;[o;
;[I"Message as a string.;T@o;;[I"/logger.error "Argument #{@foo} mismatch."
;T;0o;;0;[o;
;[I"With progname.;T@o;;[I"5logger.info('initialize') { "Initializing..." }
;T;0o;;0;[o;
;[I"With severity.;T@o;;[I"2logger.add(Logger::FATAL) { 'Fatal error!' }
;T;0o;
;[I"KThe block form allows you to create potentially complex log messages, ;TI"Cbut to delay their evaluation until and unless the message is ;TI"4logged. For example, if we have the following:;T@o;;[I"Jlogger.debug { "This is a " + potentially + " expensive operation" }
;T;0o;
;[I"RIf the logger's level is +INFO+ or higher, no debug messages will be logged, ;TI"Gand the entire block will not even be evaluated. Compare to this:;T@o;;[I"Glogger.debug("This is a " + potentially + " expensive operation")
;T;0o;
;[I"HHere, the string concatenation is done every time, even if the log ;TI"0level is not set to show the debug message.;T@S; ;
i; I"How to close a logger;T@o;;[I"logger.close
;T;0S; ;
i; I" Setting severity threshold;T@o;;;;[ o;;0;[o;
;[I"Original interface.;T@o;;[I")logger.sev_threshold = Logger::WARN
;T;0o;;0;[o;
;[I"+Log4r (somewhat) compatible interface.;T@o;;[I"!logger.level = Logger::INFO
;TI"
;TI"5# DEBUG < INFO < WARN < ERROR < FATAL < UNKNOWN
;T;0o;;0;[o;
;[I"(Symbol or String (case insensitive);T@o;;[ I"logger.level = :info
;TI"logger.level = 'INFO'
;TI"
;TI";# :debug < :info < :warn < :error < :fatal < :unknown
;T;0o;;0;[o;
;[I"Constructor;T@o;;[I"-Logger.new(logdev, level: Logger::INFO)
;TI"&Logger.new(logdev, level: :info)
;TI"'Logger.new(logdev, level: 'INFO')
;T;0S; ;
i; I" Format;T@o;
;[I"KLog messages are rendered in the output stream in a certain format by ;TI"?default. The default format and a sample are shown below:;T@o;
;[I"Log format:;To;;[I"DSeverityID, [DateTime #pid] SeverityLabel -- ProgName: message
;T;0o;
;[I"Log sample:;To;;[I"AI, [1999-03-03T02:34:24.895701 #19074] INFO -- Main: info.
;T;0o;
;[I"CYou may change the date and time format via #datetime_format=.;T@o;;[I"2logger.datetime_format = '%Y-%m-%d %H:%M:%S'
;TI"( # e.g. "2004-01-03 00:54:26"
;T;0o;
;[I" or via the constructor.;T@o;;[I">Logger.new(logdev, datetime_format: '%Y-%m-%d %H:%M:%S')
;T;0o;
;[I"FOr, you may change the overall format via the #formatter= method.;T@o;;[ I"Dlogger.formatter = proc do |severity, datetime, progname, msg|
;TI" "#{datetime}: #{msg}\n"
;TI" end
;TI"5# e.g. "2005-09-22 08:51:08 +0900: hello world"
;T;0o;
;[I" or via the constructor.;T@o;;[I"MLogger.new(logdev, formatter: proc {|severity, datetime, progname, msg|
;TI" "#{datetime}: #{msg}\n"
;TI"});T;0:
@fileI"lib/logger.rb;T:0@omit_headings_from_table_of_contents_below0;0;0[ [
I"formatter;TI"RW;T: publicFI"lib/logger.rb;T[
I"
level;TI"R;T;F@b[
I"
progname;TI"RW;T;F@b[
I"sev_threshold;F@e;F@b[U:RDoc::Constant[i I" VERSION;FI"Logger::VERSION;T00o;;[ ;@];0@]@cRDoc::NormalClass0U;[i I"
ProgName;FI"Logger::ProgName;T00o;;[ ;@];0@]@@r0U;[i I"SEV_LABEL;FI"Logger::SEV_LABEL;T00o;;[o;
;[I".Severity label for logging (max 5 chars).;T;@];0@]@@r0[[I"
Severity;To;;[ ;@];0@b[[I"
class;T[[;[[I"new;T@b[:protected[ [: private[ [I"
instance;T[[;[[I"<<;T@b[I"add;F@b[I"
close;F@b[I"datetime_format;F@b[I"datetime_format=;F@b[I"
debug;F@b[I" debug?;F@b[I"
error;F@b[I" error?;F@b[I"
fatal;F@b[I" fatal?;F@b[I" info;F@b[I"
info?;F@b[I" level=;F@b[I"log;F@b[I" reopen;F@b[I"sev_threshold=;F@b[I" unknown;F@b[I" warn;F@b[I"
warn?;F@b[;[ [; [[I"format_message;F@b[I"format_severity;F@b[ [U:RDoc::Context::Section[i 0o;;[ ;0;0[@]@]cRDoc::TopLevel
Mini Shell