sml-log4r 1.0.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- data/doc/content/contact.html +22 -0
- data/doc/content/contribute.html +21 -0
- data/doc/content/index.html +90 -0
- data/doc/content/license.html +56 -0
- data/doc/content/manual.html +449 -0
- data/doc/dev/README.developers +40 -0
- data/doc/dev/checklist +14 -0
- data/doc/dev/things-to-do +2 -0
- data/doc/images/crush/logo2.png +0 -0
- data/doc/images/log4r-logo.png +0 -0
- data/doc/images/logo2.png +0 -0
- data/doc/log4r.css +111 -0
- data/doc/old/manual.html +348 -0
- data/doc/templates/main.html +147 -0
- data/examples/README +19 -0
- data/examples/customlevels.rb +34 -0
- data/examples/fileroll.rb +40 -0
- data/examples/log4r_yaml.yaml +0 -0
- data/examples/logclient.rb +25 -0
- data/examples/logserver.rb +18 -0
- data/examples/moderate.xml +29 -0
- data/examples/moderateconfig.rb +66 -0
- data/examples/myformatter.rb +23 -0
- data/examples/outofthebox.rb +21 -0
- data/examples/rrconfig.xml +63 -0
- data/examples/rrsetup.rb +42 -0
- data/examples/simpleconfig.rb +39 -0
- data/examples/xmlconfig.rb +25 -0
- data/examples/yaml.rb +30 -0
- data/src/log4r.rb +17 -0
- data/src/log4r/base.rb +74 -0
- data/src/log4r/config.rb +9 -0
- data/src/log4r/configurator.rb +224 -0
- data/src/log4r/formatter/formatter.rb +105 -0
- data/src/log4r/formatter/patternformatter.rb +108 -0
- data/src/log4r/lib/drbloader.rb +52 -0
- data/src/log4r/lib/xmlloader.rb +24 -0
- data/src/log4r/logevent.rb +28 -0
- data/src/log4r/logger.rb +194 -0
- data/src/log4r/loggerfactory.rb +89 -0
- data/src/log4r/logserver.rb +28 -0
- data/src/log4r/outputter/consoleoutputters.rb +18 -0
- data/src/log4r/outputter/datefileoutputter.rb +110 -0
- data/src/log4r/outputter/emailoutputter.rb +115 -0
- data/src/log4r/outputter/fileoutputter.rb +49 -0
- data/src/log4r/outputter/iooutputter.rb +55 -0
- data/src/log4r/outputter/outputter.rb +132 -0
- data/src/log4r/outputter/outputterfactory.rb +59 -0
- data/src/log4r/outputter/remoteoutputter.rb +40 -0
- data/src/log4r/outputter/rollingfileoutputter.rb +126 -0
- data/src/log4r/outputter/staticoutputter.rb +30 -0
- data/src/log4r/outputter/syslogoutputter.rb +75 -0
- data/src/log4r/rdoc/configurator +243 -0
- data/src/log4r/rdoc/emailoutputter +103 -0
- data/src/log4r/rdoc/formatter +39 -0
- data/src/log4r/rdoc/log4r +89 -0
- data/src/log4r/rdoc/logger +175 -0
- data/src/log4r/rdoc/logserver +85 -0
- data/src/log4r/rdoc/outputter +108 -0
- data/src/log4r/rdoc/patternformatter +128 -0
- data/src/log4r/rdoc/syslogoutputter +29 -0
- data/src/log4r/rdoc/yamlconfigurator +20 -0
- data/src/log4r/repository.rb +65 -0
- data/src/log4r/staticlogger.rb +49 -0
- data/src/log4r/yamlconfigurator.rb +0 -0
- data/tests/include.rb +7 -0
- data/tests/runtest.rb +6 -0
- data/tests/testbase.rb +45 -0
- data/tests/testcustom.rb +33 -0
- data/tests/testdefault.rb +25 -0
- data/tests/testformatter.rb +29 -0
- data/tests/testlogger.rb +198 -0
- data/tests/testoutputter.rb +112 -0
- data/tests/testpatternformatter.rb +26 -0
- data/tests/testxmlconf.rb +51 -0
- data/tests/xml/testconf.xml +37 -0
- metadata +140 -0
@@ -0,0 +1,175 @@
|
|
1
|
+
= Loggers
|
2
|
+
|
3
|
+
Loggers provide the interface for logging in Log4r. To create a logger,
|
4
|
+
first come up with a name for it. Good choices include the name of the
|
5
|
+
class using it, a service name, or the name of the file.
|
6
|
+
|
7
|
+
To create a logger named 'mylog':
|
8
|
+
|
9
|
+
Logger.new('mylog')
|
10
|
+
|
11
|
+
After creating a logger, it is stashed in a repository. The logger may
|
12
|
+
be retrieved at any time:
|
13
|
+
|
14
|
+
Logger['mylog'] # get mylog back
|
15
|
+
|
16
|
+
It will return nil if the logger is not found. Alternatively, if an
|
17
|
+
Exception is desired when a nonexistant logger is referenced, the Logger#get
|
18
|
+
command can be used:
|
19
|
+
|
20
|
+
Logger.get('boguslog') # raises NameError if it doesn't exist
|
21
|
+
|
22
|
+
== Manipulating a Logger's Outputters
|
23
|
+
|
24
|
+
Loggers start out with no outputters. They can be added using the
|
25
|
+
Logger#add method or set directly by modifying the Loggers#outputters array:
|
26
|
+
|
27
|
+
mylog = Logger['mylog']
|
28
|
+
|
29
|
+
# assume we've created Outputters out1 through out4
|
30
|
+
mylog.outputters = out1, out2
|
31
|
+
mylog.add(out3, out4)
|
32
|
+
mylog.each_outputter {|o| o.flush}
|
33
|
+
|
34
|
+
# assume out5 through out7 have names 'out5' through 'out7' resp.
|
35
|
+
mylog.outputters = 'out5', 'out6'
|
36
|
+
mylog.add('out7')
|
37
|
+
mylog.remove('out5','out7')
|
38
|
+
|
39
|
+
Please see log4r/outputter/outputter.rb and Log4r::Outputter for more about
|
40
|
+
outputters.
|
41
|
+
|
42
|
+
== Logging Methods
|
43
|
+
|
44
|
+
To log something at a certain priority, use the logging method named
|
45
|
+
after the lowercased priority level name:
|
46
|
+
|
47
|
+
mylog.warn "This is a message with priority WARN"
|
48
|
+
mylog.fatal "A FATAL message"
|
49
|
+
|
50
|
+
Blocks can also be logged:
|
51
|
+
|
52
|
+
mylog.warn {"This is also a message with priority WARN"}
|
53
|
+
mylog.debug do
|
54
|
+
# some complicated string magic
|
55
|
+
return result
|
56
|
+
end
|
57
|
+
|
58
|
+
The primary difference is that the block doesn't get called unless
|
59
|
+
the Logger can log at that level. It is useful for doing computationaly
|
60
|
+
expensive things at a log event.
|
61
|
+
|
62
|
+
== Query Methods
|
63
|
+
|
64
|
+
To ask Log4r whether it is capable of logging a certain level:
|
65
|
+
|
66
|
+
mylog.warn? # are we logging WARN?
|
67
|
+
mylog.fatal? # how about FATAL?
|
68
|
+
|
69
|
+
Query methods and blocks accomplish the same thing:
|
70
|
+
|
71
|
+
mylog.warn "don't evaluate unless WARN is on" if mylog.warn?
|
72
|
+
mylog.warn {"don't evaluate unless WARN is on"}
|
73
|
+
|
74
|
+
== What About the Special Levels?
|
75
|
+
|
76
|
+
<tt>ALL</tt> and <tt>OFF</tt> can be querried, but not logged:
|
77
|
+
|
78
|
+
log.off? # true iff level is OFF
|
79
|
+
log.all? # true iff level is ALL
|
80
|
+
log.all "Try to log" => Method not defined. (NameError)
|
81
|
+
|
82
|
+
== Custom Levels and Method Names
|
83
|
+
|
84
|
+
Suppose we've set up Log4r with the custom levels:
|
85
|
+
|
86
|
+
Foo < Bar < Baz
|
87
|
+
|
88
|
+
As one might expect, the logging methods are named after them:
|
89
|
+
|
90
|
+
log.bar "something" # log at custom level Bar
|
91
|
+
log.bar? # are we logging at level Bar?
|
92
|
+
|
93
|
+
= Logger Inheritance
|
94
|
+
|
95
|
+
Normally, when a logger is created, its parent is set to RootLogger.
|
96
|
+
If a Logger's level isn't specified at creation, it will inherit the level
|
97
|
+
of its parent.
|
98
|
+
|
99
|
+
To specify an ancestors of a logger besides RootLogger, include the names
|
100
|
+
of the ancestors in order of ancestry and delimited by
|
101
|
+
Log4r::Log4rConfig::LoggerPathDelimiter. For example, if the
|
102
|
+
delimiter is the default <tt>::</tt>, our logger is 'me'
|
103
|
+
and its ancestors are 'cain', 'grandpa', and 'pa', we create the logger
|
104
|
+
like so:
|
105
|
+
|
106
|
+
Logger.new('cain::grandpa::pa::me')
|
107
|
+
|
108
|
+
This string is split into three compontents which can be used
|
109
|
+
by a Formatter to avoid parsing the name:
|
110
|
+
|
111
|
+
Logger#fullname:: The whole enchilada: 'cain::grandpa::pa::me'
|
112
|
+
Logger#name:: Just 'me'
|
113
|
+
|
114
|
+
To get this logger back from the repository,
|
115
|
+
|
116
|
+
Logger['cain::grandpa::pa::me']
|
117
|
+
|
118
|
+
= Outputter Additivity
|
119
|
+
|
120
|
+
By default, Logger Outputters are <b>additive</b>. This means that
|
121
|
+
a log event will also be sent to all of a logger's ancestors. To
|
122
|
+
stop this behavior, set a logger's +additive+ to false.
|
123
|
+
|
124
|
+
Logger['foo'].additive = false
|
125
|
+
|
126
|
+
A Logger's level, additivity and trace can be changed dynamically,
|
127
|
+
but this is an expensive operation as the logging methods have to be
|
128
|
+
redefined.
|
129
|
+
|
130
|
+
= RootLogger
|
131
|
+
|
132
|
+
Log4r::RootLogger is the ancestor of all loggers. Its level defines the global
|
133
|
+
logging threshold. Any loggers created <b>after</b> RootLogger's level is
|
134
|
+
set will not log below that level. By default, RootLogger's level is set
|
135
|
+
to <tt>ALL</tt>
|
136
|
+
|
137
|
+
RootLogger is a singleton which gets created automaticallay. It can be
|
138
|
+
retrieved at any time with Logger.root, Logger.global,
|
139
|
+
Logger['root'] or Logger['global'].
|
140
|
+
|
141
|
+
== Global Level
|
142
|
+
|
143
|
+
Suppose we want _everything_ to ignore events less than FATAL. We can
|
144
|
+
accomplish this easily:
|
145
|
+
|
146
|
+
Logger.global.level = FATAL
|
147
|
+
|
148
|
+
Just be sure to set this before any other Loggers or Outputters are defined.
|
149
|
+
|
150
|
+
== RootLogger Does Nothing
|
151
|
+
|
152
|
+
RootLogger itself behaves as if its level were permanently set to
|
153
|
+
<tt>OFF</tt>, thus making it a sort of null object.
|
154
|
+
|
155
|
+
= XML Configuration
|
156
|
+
|
157
|
+
Please see log4r/configurator.rb for an overview of XML configuratoin.
|
158
|
+
|
159
|
+
It's easy to configure a Logger in XML. The following example should be
|
160
|
+
sufficient:
|
161
|
+
|
162
|
+
...
|
163
|
+
<logger name="papa::mylog" level="DEBUG" trace="true">
|
164
|
+
<additive>false</additive>
|
165
|
+
<outputter>stdout</outputter>
|
166
|
+
<outputters>stderr, dancer, doner, blitzen</outputters>
|
167
|
+
</logger>
|
168
|
+
<logger name="papa" outputters="stderr, stdout"/>
|
169
|
+
...
|
170
|
+
|
171
|
+
The element +outputter+ can occur multiple times, but cannot be an attribute
|
172
|
+
of +logger+. That is, it is not an <i>XML directive</i>. However, the element
|
173
|
+
+outputters+ is an <i>XML directive</i>, as are all the others.
|
174
|
+
|
175
|
+
For more examples, check the <tt>examples</tt> directory in the Log4r package.
|
@@ -0,0 +1,85 @@
|
|
1
|
+
= Remote Logging
|
2
|
+
|
3
|
+
Want to use Log4r over a network? No problem! A Log4r::RemoteOutputter will
|
4
|
+
send its LogEvents to a Log4r::LogServer. These two classes are as easy to
|
5
|
+
set up and use as the rest of Log4r.
|
6
|
+
|
7
|
+
== Use ROMP
|
8
|
+
|
9
|
+
There is one catch though: ROMP is required to use this service. It is a
|
10
|
+
DRb-like system with superb performance and better features. Get ROMP at
|
11
|
+
http://rubystuff.org/romp/
|
12
|
+
|
13
|
+
== LogServer
|
14
|
+
|
15
|
+
LogServer is simply a kind of Logger which embeds a ROMP::Server. Like a
|
16
|
+
normal Logger, you can give it Outputters, set its level and so on. Its
|
17
|
+
logging methods are accessible over a network and are called by a
|
18
|
+
RemoteOutputter on another host.
|
19
|
+
|
20
|
+
=== LogServer Setup
|
21
|
+
|
22
|
+
Setup is easy. First,
|
23
|
+
|
24
|
+
require 'log4r/logserver'
|
25
|
+
|
26
|
+
The following sets up a LogServer named 'central' on localhost port 9999:
|
27
|
+
|
28
|
+
LogServer.new('central', 'tcpromp://localhost:9999')
|
29
|
+
|
30
|
+
We manipulate it and give it outputters as normal:
|
31
|
+
|
32
|
+
serv = Logger['central'] # grab our new LogServer
|
33
|
+
serv.add 'stdout' # make it log to $stdout
|
34
|
+
|
35
|
+
== RemoteOutputter
|
36
|
+
|
37
|
+
RemoteOutputter is simply a kind of Outputter that embeds a ROMP::Client. When
|
38
|
+
RemoteOutputter gets a LogEvent, it will forward it to whatever LogServer it's
|
39
|
+
connected to. In essence, RemoteOutputter behaves like a Logger that is
|
40
|
+
forwarding a LogEvent to another Logger (as is done in hierarchical logging).
|
41
|
+
|
42
|
+
=== RemoteOutputter Setup
|
43
|
+
|
44
|
+
First,
|
45
|
+
|
46
|
+
require 'log4r/outputter/remoteoutputter'
|
47
|
+
|
48
|
+
Unlike typical outputters, RemoteOutputter doesn't do any formatting. That's
|
49
|
+
up to the LogServer's outputters. Otherwise, RemoteOutputter can be
|
50
|
+
set up as usual. The ROMP uri of the LogServer must be specified.
|
51
|
+
|
52
|
+
RemoteOutputter.new 'client', :uri=>'tcpromp://localhost:9999'
|
53
|
+
|
54
|
+
=== Using RemoteOutputter
|
55
|
+
|
56
|
+
Give our new RemoteOutputter to a logger:
|
57
|
+
|
58
|
+
mylog = Logger['mylog']
|
59
|
+
mylog.add 'client'
|
60
|
+
|
61
|
+
Now, whenever mylog generates a LogEvent, LogServer should get a copy. Doing
|
62
|
+
the following:
|
63
|
+
|
64
|
+
mylog.info "This is a message from 'mylog'"
|
65
|
+
|
66
|
+
Produces this output on LogServer's console:
|
67
|
+
|
68
|
+
INFO mylog: This is a message from 'mylog'
|
69
|
+
|
70
|
+
== XML Configuration
|
71
|
+
|
72
|
+
RemoteOutputter is set up like normal Outputters. LogServer is set up
|
73
|
+
like a normal Logger, but with an element name of logserver instead of
|
74
|
+
logger:
|
75
|
+
|
76
|
+
<log4r_config>
|
77
|
+
<logserver name="name" uri="tcpromp://localhost:9999">
|
78
|
+
...
|
79
|
+
|
80
|
+
== Debugging
|
81
|
+
|
82
|
+
It is recommended to set up a logger named 'log4r' on both the server and
|
83
|
+
client to see what LogServer and RemoteOutputter are up to. Both of the classes
|
84
|
+
use Log4r's internal logging to report any problems. See the section
|
85
|
+
<b>What's Going on Inside?</b> in log4r.rb for more info.
|
@@ -0,0 +1,108 @@
|
|
1
|
+
= Outputters
|
2
|
+
|
3
|
+
An Outputter is a logging destination with a particular way to format
|
4
|
+
data. It has a level threshold and a flexible level mask.
|
5
|
+
|
6
|
+
Outputters must have names.
|
7
|
+
|
8
|
+
== Level Threshold
|
9
|
+
|
10
|
+
Outputters have their own level thresholds that default to <tt>root</tt>
|
11
|
+
level. They will not write any log events with a rank less than their
|
12
|
+
threshold.
|
13
|
+
|
14
|
+
== Level Mask
|
15
|
+
|
16
|
+
Alternatively, an Outputter can be told to log specific levels only:
|
17
|
+
|
18
|
+
o = StdoutOutputter.new 'console'
|
19
|
+
o.only_at DEBUG, FATAL # only DEBUG and FATAL get written
|
20
|
+
|
21
|
+
== Outputter Repository
|
22
|
+
|
23
|
+
When outputters are created, they store themselves in an Outputter
|
24
|
+
repository similar to the Logger repository.
|
25
|
+
|
26
|
+
StdoutOutputter.new 'console' => Create 'console' outputter
|
27
|
+
Outputter['console'] => Get it back from the stash.
|
28
|
+
|
29
|
+
== Formatter
|
30
|
+
|
31
|
+
An outputter has a format defined by its Formatter. If no Formatter
|
32
|
+
is specified, DefaultFormatter will be used.
|
33
|
+
|
34
|
+
== Outputter is Abstract
|
35
|
+
|
36
|
+
The basic Outputter class is both abstract and a null object.
|
37
|
+
|
38
|
+
== Interesting Outputters
|
39
|
+
|
40
|
+
* log4r/outputter/syslogoutputter.rb - Logs to syslog
|
41
|
+
* log4r/outputter/emailoutputter.rb - Email logs
|
42
|
+
* log4r/logserver.rb - For remote logging
|
43
|
+
|
44
|
+
== Subclasses
|
45
|
+
|
46
|
+
* Log4r::IOOutputter - for any IO object
|
47
|
+
* Log4r::StdoutOutputter - $stdout
|
48
|
+
* Log4r::StderrOutputter - $stderr
|
49
|
+
* Log4r::FileOutputter - log to a file
|
50
|
+
* Log4r::RollingFileOutputter - log to a file and split it as it grows
|
51
|
+
* Log4r::SyslogOutputter - logs to syslog
|
52
|
+
* Log4r::EmailOutputter - email logs
|
53
|
+
* Log4r::RemoteOutputter - for remote logging
|
54
|
+
|
55
|
+
== Default Outputters
|
56
|
+
|
57
|
+
Two outputters named 'stdout' and 'stderr' are created automatically at
|
58
|
+
the root level. They are nice shortcuts.
|
59
|
+
|
60
|
+
Outputter['stdout'] => 'stdout'
|
61
|
+
Outputter['stderr'] => 'stderr'
|
62
|
+
Outputter.stdout => 'stdout'
|
63
|
+
Outputter.stderr => 'stderr'
|
64
|
+
|
65
|
+
== Configuring
|
66
|
+
|
67
|
+
Outputters must have names and receive hash arguments. The parameter name
|
68
|
+
for the hash args can be either a symbol or a string. All defined outputters
|
69
|
+
accept <tt>:level</tt> and <tt>:formatter</tt> arguments. For arguments
|
70
|
+
specific to a convenience Outputter, please look at the class description.
|
71
|
+
|
72
|
+
The level threshold, the levels to log at (only_at) and formatter can be
|
73
|
+
changed dynamically using the <tt>=</tt> methods.
|
74
|
+
|
75
|
+
As a collective example of all this, here are various ways to set up an
|
76
|
+
IOOutputter:
|
77
|
+
|
78
|
+
IOOutputter.new ExoticIO.new 'exotic', 'level' => WARN,
|
79
|
+
:formatter => MyFormatter.new
|
80
|
+
# an equivalent way:
|
81
|
+
o = IOOutputter.new ExoticIO.new 'exotic'
|
82
|
+
o.level = WARN
|
83
|
+
o.formatter = MyFormatter # we can specify just the class
|
84
|
+
o.only_at = THIS, THAT
|
85
|
+
|
86
|
+
== XML Configuration
|
87
|
+
|
88
|
+
Specify outputters as children of <tt><log4r_config></tt>:
|
89
|
+
|
90
|
+
<log4r_config>
|
91
|
+
<outputter name="myout" type="Log4r::StdoutOutputter">
|
92
|
+
<only_at>DEBUG, INFO</only_at>
|
93
|
+
</outputter>
|
94
|
+
<outputter name="file" level="WARN">
|
95
|
+
<type>FileOutputter</type>
|
96
|
+
<filename>#{logpath}/file.log</filename>
|
97
|
+
<trunc>false</trunc>
|
98
|
+
</outputter>
|
99
|
+
...
|
100
|
+
|
101
|
+
As explained in log4r/configurator.rb, the hash arguments you would normally
|
102
|
+
pass to <tt>new</tt> are specified as <i>XML parameters</i>.
|
103
|
+
It is given an IO object to write
|
104
|
+
to, a Formatter to call, and, optionally, levels to write at.
|
105
|
+
|
106
|
+
Outputters invoke print then flush on the wrapped IO object.
|
107
|
+
If the IO chokes, the Outputter will close the IO and set its
|
108
|
+
level to <tt>OFF</tt>.
|
@@ -0,0 +1,128 @@
|
|
1
|
+
= PatternFormatter
|
2
|
+
|
3
|
+
PatternFormatter offers complete control over the appearance of
|
4
|
+
Log4r log events without having to write custom Formatter classes.
|
5
|
+
In order to take advantage of PatternFormatter, some familarity with
|
6
|
+
Kernel#sprintf or the C printf function is recommended. For time formatting,
|
7
|
+
please look at Time.strftime.
|
8
|
+
|
9
|
+
PatternFormatter accepts three hash arguments:
|
10
|
+
|
11
|
+
<tt>pattern</tt>:: Log event format string.
|
12
|
+
<tt>date_pattern</tt>:: Date format string.
|
13
|
+
<tt>date_method</tt>:: <tt>Time</tt> method to call (instead of using date_pattern).
|
14
|
+
|
15
|
+
|
16
|
+
The <tt>pattern</tt> format string is something like "%l [%d] %80M",
|
17
|
+
which resembles a pattern one would normally pass to Kernel#sprintf. However,
|
18
|
+
the directives are specific to Log4r. Before we go on, let's cover some
|
19
|
+
terminology.
|
20
|
+
|
21
|
+
== Terminology
|
22
|
+
|
23
|
+
[<b>%</b>] The directive identifier. Everything after this up to and
|
24
|
+
including one of the <em>directive letters</em> defines a
|
25
|
+
<em>directive</em>.
|
26
|
+
[<b>directive letter</b>]
|
27
|
+
Letters in the set <tt>[cCdtmMl%]</tt>. These
|
28
|
+
identify what kind of data we're interested in.
|
29
|
+
They are detailed below.
|
30
|
+
[<b>format directive</b>]
|
31
|
+
The numbers and assorted symbols that appears
|
32
|
+
between <b>%</b> and a <em>directive letter</em>
|
33
|
+
is a format directive. It is comprised of an
|
34
|
+
integer specifying the field width followed
|
35
|
+
optionally by a period and an integer specifying
|
36
|
+
the precision. The field width is the minimum
|
37
|
+
number of characters to copy from the data string
|
38
|
+
while the precision is the maximum number to copy.
|
39
|
+
If the field width is preceded by a - sign, the
|
40
|
+
data will be left-justified. Otherwise, it is
|
41
|
+
right-justified.
|
42
|
+
[<b>directive</b>]
|
43
|
+
A statement that says, "I want this data to appear with
|
44
|
+
this (optional) particular format." A directive starts
|
45
|
+
with a <b>%</b> and is followed by a format directive and
|
46
|
+
terminates in a directive letter.
|
47
|
+
|
48
|
+
== What the Directive Letters mean
|
49
|
+
|
50
|
+
[<b>c</b>] Produces a logger's name. Fast.
|
51
|
+
[<b>C</b>] Produces a logger's full name. Fast.
|
52
|
+
[<b>d</b>] Produces the time in a format specified by <b>date_pattern</b> or
|
53
|
+
by <b>date_method</b>. If neither is specified, the default will
|
54
|
+
be used (ISO8601). Slow.
|
55
|
+
[<b>t</b>] Produces the file and line number of the log event. The
|
56
|
+
appearance varies by Ruby version, but it is the same output
|
57
|
+
returned by Kernel#caller[0]. Slow.
|
58
|
+
[<b>m</b>] The non-inspected log message. That is, to_s called on the object
|
59
|
+
passed into a log method. Fast.
|
60
|
+
[<b>M</b>] The message formatted by the <tt>format_object</tt> method in
|
61
|
+
BasicFormatter. It will pretty-print Exceptions, print Strings
|
62
|
+
and inspect everything else. Slow.
|
63
|
+
[<b>l</b>] The name of the level. That's l as in Lambda. Fast.
|
64
|
+
[<b>%</b>] %% just prints a %. Any formatting is <em>probably</em> ignored.
|
65
|
+
Fast.
|
66
|
+
|
67
|
+
== Examples of directives:
|
68
|
+
|
69
|
+
|
70
|
+
[<b>%d</b>] Prints out the date according to our date_pattern or
|
71
|
+
date_method. By default, it looks like this: 2001-01-12 13:15:50
|
72
|
+
[<b>%.120m</b>] Prints out at most 120 characters of the log message.
|
73
|
+
[<b>%15t</b>] Prints the execution trace and pads it on the left with
|
74
|
+
enough whitespace to make the whole thing 15 chars.
|
75
|
+
|
76
|
+
== Pattern String
|
77
|
+
|
78
|
+
A pattern string is simply a bunch of directives combined with the desired
|
79
|
+
format. For instance, to show the level in brackets followed by the date
|
80
|
+
and then the log message trimmed to 15 characters, we use the following
|
81
|
+
pattern:
|
82
|
+
|
83
|
+
"[%l] %d :: %.15m" #=> [DEBUG] 2001-01-12 13:15:50 :: This is a messa
|
84
|
+
|
85
|
+
To create a PatternFormatter with this format:
|
86
|
+
|
87
|
+
p = PatternFormatter.new(:pattern => "[%l] %d :: %.15m")
|
88
|
+
|
89
|
+
== Formatting time
|
90
|
+
|
91
|
+
To format time, do one of the following:
|
92
|
+
|
93
|
+
* Specify a date_pattern
|
94
|
+
* Specify what class method of Ruby's <tt>Time</tt> class to call.
|
95
|
+
* Use the default format
|
96
|
+
|
97
|
+
If neither date_pattern nor date_method is specified, the default date
|
98
|
+
format will be used. Currently, that would be ISO8601,
|
99
|
+
|
100
|
+
The date_pattern is exactly what one would pass to <tt>Time.strftime</tt>.
|
101
|
+
To specify a date_pattern, pass
|
102
|
+
<tt>:date_pattern=>"pattern"</tt> to PatternFormat.new.
|
103
|
+
|
104
|
+
Alternatively, date_method can be specified to produce the output of
|
105
|
+
a specific <tt>Time</tt> method, such as <tt>usec</tt> or <tt>to_s</tt>
|
106
|
+
or any other zero argument <tt>Time</tt> method that produces a time. More
|
107
|
+
precisely, the method to call will be invoked on <tt>Time.now</tt>.
|
108
|
+
To specify a date_method, pass <tt>:date_method=>'methodname'</tt> (or a
|
109
|
+
Symbol equivalent) to <tt>PatternFormatter.new</tt>.
|
110
|
+
|
111
|
+
= XML Configuration
|
112
|
+
|
113
|
+
As explained in log4r/configurator.rb, the hash arguments to PatternFormatter
|
114
|
+
are <i>XML parameters</i>. Here's an example:
|
115
|
+
|
116
|
+
<formatter type="PatternFormatter" pattern="[%l] %d :: %.15m">
|
117
|
+
<date_method>usec</date_method>
|
118
|
+
</formatter>
|
119
|
+
|
120
|
+
= Performace considerations
|
121
|
+
|
122
|
+
The performance impact of using a particular directive letter is noted in
|
123
|
+
the <b>What the Directives Letters mean</b> section.
|
124
|
+
|
125
|
+
The performance impact of time formatting merits special attention. If you
|
126
|
+
aren't aware yet, the Time class is kind of a kludge. Time.now.usec happens
|
127
|
+
to be faster than Time.now. If you're concerned about performance, please
|
128
|
+
profile the various time methods and patterns.
|