Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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