1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
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
|
= Outputters
An Outputter is a logging destination with a particular way to format
data. It has a level threshold and a flexible level mask.
Outputters must have names.
== Level Threshold
Outputters have their own level thresholds that default to <tt>root</tt>
level. They will not write any log events with a rank less than their
threshold.
== Level Mask
Alternatively, an Outputter can be told to log specific levels only:
o = StdoutOutputter.new 'console'
o.only_at DEBUG, FATAL # only DEBUG and FATAL get written
== Outputter Repository
When outputters are created, they store themselves in an Outputter
repository similar to the Logger repository.
StdoutOutputter.new 'console' => Create 'console' outputter
Outputter['console'] => Get it back from the stash.
== Formatter
An outputter has a format defined by its Formatter. If no Formatter
is specified, DefaultFormatter will be used.
== Outputter is Abstract
The basic Outputter class is both abstract and a null object.
== Interesting Outputters
* log4r/outputter/syslogoutputter.rb - Logs to syslog
* log4r/outputter/emailoutputter.rb - Email logs
* log4r/logserver.rb - For remote logging
== Subclasses
* Log4r::IOOutputter - for any IO object
* Log4r::StdoutOutputter - $stdout
* Log4r::StderrOutputter - $stderr
* Log4r::FileOutputter - log to a file
* Log4r::RollingFileOutputter - log to a file and split it as it grows
* Log4r::SyslogOutputter - logs to syslog
* Log4r::EmailOutputter - email logs
* Log4r::RemoteOutputter - for remote logging
== Default Outputters
Two outputters named 'stdout' and 'stderr' are created automatically at
the root level. They are nice shortcuts.
Outputter['stdout'] => 'stdout'
Outputter['stderr'] => 'stderr'
Outputter.stdout => 'stdout'
Outputter.stderr => 'stderr'
== Configuring
Outputters must have names and receive hash arguments. The parameter name
for the hash args can be either a symbol or a string. All defined outputters
accept <tt>:level</tt> and <tt>:formatter</tt> arguments. For arguments
specific to a convenience Outputter, please look at the class description.
The level threshold, the levels to log at (only_at) and formatter can be
changed dynamically using the <tt>=</tt> methods.
As a collective example of all this, here are various ways to set up an
IOOutputter:
IOOutputter.new ExoticIO.new 'exotic', 'level' => WARN,
:formatter => MyFormatter.new
# an equivalent way:
o = IOOutputter.new ExoticIO.new 'exotic'
o.level = WARN
o.formatter = MyFormatter # we can specify just the class
o.only_at = THIS, THAT
== XML Configuration
Specify outputters as children of <tt><log4r_config></tt>:
<log4r_config>
<outputter name="myout" type="Log4r::StdoutOutputter">
<only_at>DEBUG, INFO</only_at>
</outputter>
<outputter name="file" level="WARN">
<type>FileOutputter</type>
<filename>#{logpath}/file.log</filename>
<trunc>false</trunc>
</outputter>
...
As explained in log4r/configurator.rb, the hash arguments you would normally
pass to <tt>new</tt> are specified as <i>XML parameters</i>.
It is given an IO object to write
to, a Formatter to call, and, optionally, levels to write at.
Outputters invoke print then flush on the wrapped IO object.
If the IO chokes, the Outputter will close the IO and set its
level to <tt>OFF</tt>.
|
