Skip to content
Newer
Older
100644 225 lines (175 sloc) 7.83 KB
7bcf044 @Vagabond Initial import
Vagabond authored Jun 24, 2011
1 * Overview
7e68976 @Vagabond Try to improve M:F(A) printing a little
Vagabond authored Jul 5, 2011
2 Lager (as in the beer) is a logging framework for Erlang. Its purpose is
7bcf044 @Vagabond Initial import
Vagabond authored Jun 24, 2011
3 to provide a more traditional way to perform logging in an erlang application
4 that plays nicely with traditional UNIX logging tools like logrotate and
5 syslog.
6
ec60541 @seancribbs Fix build status badge [ci skip]
seancribbs authored Jun 26, 2012
7 [[http://travis-ci.org/basho/lager][Travis-CI]] :: [[https://secure.travis-ci.org/basho/lager.png]]
b5f7361 @seancribbs Add Travis CI hook and build status.
seancribbs authored Jun 26, 2012
8
9 * Features
7bcf044 @Vagabond Initial import
Vagabond authored Jun 24, 2011
10 - Finer grained log levels (debug, info, notice, warning, error, critical,
11 alert, emergency)
12 - Logger calls are transformed using a parse transform to allow capturing
13 Module/Function/Line/Pid information
14 - When no handler is consuming a log level (eg. debug) no event is even sent
15 to the log handler
de705e4 @Vagabond Corrections to README
Vagabond authored Jul 8, 2011
16 - Supports multiple backends, including console and file. More are planned.
7bcf044 @Vagabond Initial import
Vagabond authored Jun 24, 2011
17
18 * Usage
19 To use lager in your application, you need to define it as a rebar dep or have
20 some other way of including it in erlang's path. You can then add the
21 following option to the erlang compiler flags
22
d4b06a0 @Vagabond Adventures in org mode
Vagabond authored Jun 24, 2011
23 #+BEGIN_EXAMPLE
7bcf044 @Vagabond Initial import
Vagabond authored Jun 24, 2011
24 {parse_transform, lager_transform}
d4b06a0 @Vagabond Adventures in org mode
Vagabond authored Jun 24, 2011
25 #+END_EXAMPLE
7bcf044 @Vagabond Initial import
Vagabond authored Jun 24, 2011
26
de21911 @Vagabond Typo
Vagabond authored Jul 14, 2011
27 Alternately, you can add it to the module you wish to compile with logging
7bcf044 @Vagabond Initial import
Vagabond authored Jun 24, 2011
28 enabled:
29
d4b06a0 @Vagabond Adventures in org mode
Vagabond authored Jun 24, 2011
30 #+BEGIN_EXAMPLE
7bcf044 @Vagabond Initial import
Vagabond authored Jun 24, 2011
31 -compile([{parse_transform, lager_transform}]).
d4b06a0 @Vagabond Adventures in org mode
Vagabond authored Jun 24, 2011
32 #+END_EXAMPLE
7bcf044 @Vagabond Initial import
Vagabond authored Jun 24, 2011
33
34 Once you have built your code with lager, you can then generate log messages
35 by doing the following:
36
d4b06a0 @Vagabond Adventures in org mode
Vagabond authored Jun 24, 2011
37 #+BEGIN_EXAMPLE
7bcf044 @Vagabond Initial import
Vagabond authored Jun 24, 2011
38 lager:error("Some message")
d4b06a0 @Vagabond Adventures in org mode
Vagabond authored Jun 24, 2011
39 #+END_EXAMPLE
7bcf044 @Vagabond Initial import
Vagabond authored Jun 24, 2011
40
41 Or:
42
d4b06a0 @Vagabond Adventures in org mode
Vagabond authored Jun 24, 2011
43 #+BEGIN_EXAMPLE
7bcf044 @Vagabond Initial import
Vagabond authored Jun 24, 2011
44 lager:warning("Some message with a term: ~p", [Term])
d4b06a0 @Vagabond Adventures in org mode
Vagabond authored Jun 24, 2011
45 #+END_EXAMPLE
7bcf044 @Vagabond Initial import
Vagabond authored Jun 24, 2011
46
47 The general form is lager:Severity() where Severity is one of the log levels
48 mentioned above.
49
50 * Configuration
9d48bae @Vagabond More README
Vagabond authored Jun 29, 2011
51 To configure lager's backends, you use an application variable (probably in
52 your app.config):
53
54 #+BEGIN_EXAMPLE
5554103 @muxspace Fixed syntax error in config example
muxspace authored Aug 11, 2011
55 {lager, [
9d48bae @Vagabond More README
Vagabond authored Jun 29, 2011
56 {handlers, [
f45f9c9 @Vagabond Typo in config example
Vagabond authored Jul 20, 2011
57 {lager_console_backend, info},
6eb8240 @Vagabond Crash log rotation & documentation on rotation
Vagabond authored Jul 19, 2011
58 {lager_file_backend, [
81d4aea @Vagabond Finish implementing time based log rotation
Vagabond authored Jul 23, 2011
59 {"error.log", error, 10485760, "$D0", 5},
60 {"console.log", info, 10485760, "$D0", 5}
6eb8240 @Vagabond Crash log rotation & documentation on rotation
Vagabond authored Jul 19, 2011
61 ]}
9d48bae @Vagabond More README
Vagabond authored Jun 29, 2011
62 ]}
5554103 @muxspace Fixed syntax error in config example
muxspace authored Aug 11, 2011
63 ]}.
9d48bae @Vagabond More README
Vagabond authored Jun 29, 2011
64 #+END_EXAMPLE
65
66 The available configuration options for each backend are listed in their
67 module's documentation.
68
69 * Error logger integration
70 Lager is also supplied with a error_logger handler module that translates
71 traditional erlang error messages into a friendlier format and sends them into
0859c90 @Vagabond Default the error_logger redirect to be on, log to the 'log' dir
Vagabond authored Jun 30, 2011
72 lager itself to be treated like a regular lager log call. To disable this, set
73 the lager application variable `error_logger_redirect' to `false'.
74
75 The error_logger handler will also log more complete error messages (protected
76 with use of trunc_io) to a "crash log" which can be referred to for further
61ae86f @Vagabond Minor documentation tweaks
Vagabond authored Jul 5, 2011
77 information. The location of the crash log can be specified by the crash_log
78 application variable. If undefined it is not written at all.
9d48bae @Vagabond More README
Vagabond authored Jun 29, 2011
79
6eb8240 @Vagabond Crash log rotation & documentation on rotation
Vagabond authored Jul 19, 2011
80 Messages in the crash log are subject to a maximum message size which can be
81 specified via the crash_log_msg_size application variable.
82
9d48bae @Vagabond More README
Vagabond authored Jun 29, 2011
83 * Runtime loglevel changes
84 You can change the log level of any lager backend at runtime by doing the
85 following:
86
87 #+BEGIN_EXAMPLE
88 lager:set_loglevel(lager_console_backend, debug).
89 #+END_EXAMPLE
90
91 Or, for the backend with multiple handles (files, mainly):
92
93 #+BEGIN_EXAMPLE
5793dfe @dreverri Fix typo in README
dreverri authored Sep 6, 2011
94 lager:set_loglevel(lager_file_backend, "console.log", debug).
9d48bae @Vagabond More README
Vagabond authored Jun 29, 2011
95 #+END_EXAMPLE
96
97 Lager keeps track of the minium log level being used by any backend and
98 supresses generation of messages lower than that level. This means that debug
99 log messages, when no backend is consuming debug messages, are effectively
de705e4 @Vagabond Corrections to README
Vagabond authored Jul 8, 2011
100 free. A simple benchmark of doing 1 million debug log messages while the
9d48bae @Vagabond More README
Vagabond authored Jun 29, 2011
101 minimum threshold was above that takes less than half a second.
81d4aea @Vagabond Finish implementing time based log rotation
Vagabond authored Jul 23, 2011
102
103 * Internal log rotation
104 Lager can rotate its own logs or have it done via an external process. To
105 use internal rotation, use the last 3 values in the file backend's
106 configuration tuple. For example
107
108 #+BEGIN_EXAMPLE
109 {"error.log", error, 10485760, "$D0", 5}
110 #+END_EXAMPLE
111
112 This tells lager to log error and above messages to "error.log" and to
113 rotate the file at midnight or when it reaches 10mb, whichever comes first
114 and to keep 5 rotated logs, in addition to the current one. Setting the
115 count to 0 does not disable rotation, it instead rotates the file and keeps
116 no previous versions around. To disable rotation set the size to 0 and the
117 date to "".
118
119 The "$D0" syntax is taken from the syntax newsyslog uses in newsyslog.conf.
120 The relevant extract follows:
121
122 #+BEGIN_EXAMPLE
123 Day, week and month time format: The lead-in character
124 for day, week and month specification is a `$'-sign.
125 The particular format of day, week and month
126 specification is: [Dhh], [Ww[Dhh]] and [Mdd[Dhh]],
127 respectively. Optional time fields default to
128 midnight. The ranges for day and hour specifications
129 are:
130
131 hh hours, range 0 ... 23
132 w day of week, range 0 ... 6, 0 = Sunday
133 dd day of month, range 1 ... 31, or the
134 letter L or l to specify the last day of
135 the month.
136
137 Some examples:
138 $D0 rotate every night at midnight
139 $D23 rotate every day at 23:00 hr
140 $W0D23 rotate every week on Sunday at 23:00 hr
141 $W5D16 rotate every week on Friday at 16:00 hr
142 $M1D0 rotate on the first day of every month at
143 midnight (i.e., the start of the day)
144 $M5D6 rotate on every 5th day of the month at
145 6:00 hr
146 #+END_EXAMPLE
147
148 To configure the crash log rotation, the following application variables are
149 used:
150 - crash_log_size
151 - crash_log_date
152 - crash_log_count
153
154 See the .app.src file for further details.
f85ea9e @Vagabond Add note on syslog backend
Vagabond authored Aug 18, 2011
155
156 * Syslog Support
5fd47ad @Vagabond Typo
Vagabond authored Dec 3, 2011
157 Lager syslog output is provided as a separate application;
f85ea9e @Vagabond Add note on syslog backend
Vagabond authored Aug 18, 2011
158 [[https://github.com/basho/lager_syslog][lager_syslog]]. It is packaged as a
159 separate application so Lager itself doesn't have an indirect dependancy on a
160 port driver. Please see the lager_syslog README for configuration information.
0e70e68 @Vagabond Add documentation & function to clear all traces
Vagabond authored Oct 26, 2011
161
570d6cb @Vagabond Add link to AMQP backend
Vagabond authored Nov 17, 2011
162 * AMQP Support
163 Jon Brisbin has written a lager backend to send lager messages into AMQP, so
164 you can aggregate logs from a cluster into a central point. You can find it
165 under the [[https://github.com/jbrisbin/lager_amqp_backend][lager_amqp_backend]]
166 project on github.
167
0e70e68 @Vagabond Add documentation & function to clear all traces
Vagabond authored Oct 26, 2011
168 * Tracing
169 Lager supports basic support for redirecting log messages based on log message
ed7bc9a @Vagabond Add pid to the list of attributes automatically captured for tracing
Vagabond authored Oct 27, 2011
170 attributes. Lager automatically captures the pid, module, function and line at the
0e70e68 @Vagabond Add documentation & function to clear all traces
Vagabond authored Oct 26, 2011
171 log message callsite. However, you can add any additional attributes you wish:
172
173 #+BEGIN_EXAMPLE
174 lager:warning([{request, RequestID},{vhost, Vhost}], "Permission denied to ~s", [User])
175 #+END_EXAMPLE
176
177 Then, in addition to the default trace attributes, you'll be able to trace
178 based on request or vhost:
179
180 #+BEGIN_EXAMPLE
181 lager:trace_file("logs/example.com.error", [{vhost, "example.com"}], error)
182 #+END_EXAMPLE
183
184 You can also omit the final argument, and the loglevel will default to
185 'debug'.
186
187 Tracing to the console is similar:
188
189 #+BEGIN_EXAMPLE
190 lager:trace_console([{request, 117}])
191 #+END_EXAMPLE
192
193 In the above example, the loglevel is omitted, but it can be specified as the
194 second argument if desired.
195
196 You can also specify multiple expressions in a filter, or use the '*' atom as
197 a wildcard to match any message that has that attribute, regardless of its
198 value.
199
200 Tracing to an existing logfile is also supported, if you wanted to log
201 warnings from a particular module to the default error.log:
202
203 #+BEGIN_EXAMPLE
204 lager:trace_file("log/error.log", [{module, mymodule}], warning)
205 #+END_EXAMPLE
206
207 To view the active log backends and traces, you can use the lager:status()
208 function. To clear all active traces, you can use lager:clear_all_traces().
c619263 @Vagabond Cleanup unused handlers when a trace is removed, documentation
Vagabond authored Oct 26, 2011
209
210 To delete a specific trace, store a handle for the trace when you create it,
211 that you later pass to lager:stop_trace/1:
212
213 #+BEGIN_EXAMPLE
214 {ok, Trace} = lager:trace_file("log/error.log", [{module, mymodule}]),
215 ...
216 lager:stop_trace(Trace)
217 #+END_EXAMPLE
ed7bc9a @Vagabond Add pid to the list of attributes automatically captured for tracing
Vagabond authored Oct 27, 2011
218
219 Tracing to a pid is somewhat of a special case, since a pid is not a
220 data-type that serializes well. To trace by pid, use the pid as a string:
221
222 #+BEGIN_EXAMPLE
223 lager:trace_console([{pid, "<0.410.0>"}])
224 #+END_EXAMPLE
Something went wrong with that request. Please try again.