From 0e70e68841514a0d5ee3dff1a2014aee11a8b584 Mon Sep 17 00:00:00 2001
From: Andrew Thompson <andrew@hijacked.us>
Date: Wed, 26 Oct 2011 13:16:04 -0400
Subject: [PATCH] Add documentation & function to clear all traces

---
 README.org    | 42 ++++++++++++++++++++++++++++++++++++++++++
 src/lager.erl |  9 +++++++--
 2 files changed, 49 insertions(+), 2 deletions(-)

diff --git a/README.org b/README.org
index de888a3..56daa23 100644
--- a/README.org
+++ b/README.org
@@ -156,3 +156,45 @@
   [[https://github.com/basho/lager_syslog][lager_syslog]]. It is packaged as a
   separate application so Lager itself doesn't have an indirect dependancy on a
   port driver. Please see the lager_syslog README for configuration information.
+
+* Tracing
+  Lager supports basic support for redirecting log messages based on log message
+  attributes. Lager automatically captures the module, function and line at the
+  log message callsite. However, you can add any additional attributes you wish:
+
+#+BEGIN_EXAMPLE
+  lager:warning([{request, RequestID},{vhost, Vhost}], "Permission denied to ~s", [User])
+#+END_EXAMPLE
+
+  Then, in addition to the default trace attributes, you'll be able to trace
+  based on request or vhost:
+
+#+BEGIN_EXAMPLE
+  lager:trace_file("logs/example.com.error", [{vhost, "example.com"}], error)
+#+END_EXAMPLE
+
+  You can also omit the final argument, and the loglevel will default to
+  'debug'.
+
+  Tracing to the console is similar:
+
+#+BEGIN_EXAMPLE
+  lager:trace_console([{request, 117}])
+#+END_EXAMPLE
+
+  In the above example, the loglevel is omitted, but it can be specified as the
+  second argument if desired.
+
+  You can also specify multiple expressions in a filter, or use the '*' atom as
+  a wildcard to match any message that has that attribute, regardless of its
+  value.
+
+  Tracing to an existing logfile is also supported, if you wanted to log
+  warnings from a particular module to the default error.log:
+
+#+BEGIN_EXAMPLE
+  lager:trace_file("log/error.log", [{module, mymodule}], warning)
+#+END_EXAMPLE
+
+  To view the active log backends and traces, you can use the lager:status()
+  function. To clear all active traces, you can use lager:clear_all_traces().
diff --git a/src/lager.erl b/src/lager.erl
index e306dff..cb5d981 100644
--- a/src/lager.erl
+++ b/src/lager.erl
@@ -23,7 +23,7 @@
 %% API
 -export([start/0,
         log/8, log_dest/9, log/3, log/4,
-        trace_file/2, trace_file/3, trace_console/1, trace_console/2,
+        trace_file/2, trace_file/3, trace_console/1, trace_console/2, clear_all_traces/0,
         status/0,
         get_loglevel/1, set_loglevel/2, set_loglevel/3, get_loglevels/0,
         minimum_loglevel/1, posix_error/1,
@@ -129,6 +129,10 @@ trace_console(Filter, Level) ->
             Error
     end.
 
+clear_all_traces() ->
+    {MinLevel, _Traces} = lager_mochiglobal:get(loglevel),
+    lager_mochiglobal:put(loglevel, {MinLevel, []}).
+
 status() ->
     Handlers = gen_event:which_handlers(lager_event),
     Status = ["Lager status:\n",
@@ -145,7 +149,8 @@ status() ->
             end || Handler <- Handlers],
         "Active Traces:\n",
         [begin
-                    io_lib:format("Tracing messages matching ~p at level ~p to ~p\n", [Filter, lager_util:num_to_level(Level), Destination])
+                    io_lib:format("Tracing messages matching ~p at level ~p to ~p\n",
+                        [Filter, lager_util:num_to_level(Level), Destination])
             end || {Filter, Level, Destination} <- element(2, lager_mochiglobal:get(loglevel))]],
     io:put_chars(Status).