Skip to content

HTTPS clone URL

Subversion checkout URL

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