Add documentation and specs for lager:install_trace and lager:remove_…

…trace

README.md

@@ -962,6 +962,25 @@ level of your application, you can use these configs to turn it off:
          {suppress_supervisor_start_stop, true}]}
 ```
 
+Sys debug functions
+--------------------
+
+Lager provides an integrated way to use sys 'debug functions'. You can install a debug
+function in a target process by doing
+
+```erlang
+lager:install_trace(Pid, notice).
+```
+
+This will, on every 'system event' for an OTP process (usually inbound messages, replies
+and state changes) generate a lager message at the specified log level.
+
+You can remove the trace when you're done by doing:
+
+```erlang
+lager:remove_trace(Pid).
+```
+
 Elixir Support
 --------------
 

src/lager.erl

@@ -45,13 +45,13 @@
 
 %% API
 
-trace_func({Pid, Level}=FuncState, Event, ProcState) ->
-    lager:log(Level, Pid, "TRACE ~p ~p", [Event, ProcState]),
-    FuncState.
-
+%% @doc installs a lager trace handler into the target process (using sys:install) at the specified level.
+-spec install_trace(pid(), log_level()) -> ok.
 install_trace(Pid, Level) ->
     sys:install(Pid, {fun ?MODULE:trace_func/3, {Pid, Level}}).
 
+%% @doc remove a previously installed lager trace handler from the target process.
+-spec remove_trace(pid()) -> ok.
 remove_trace(Pid) ->
     sys:remove(Pid, fun ?MODULE:trace_func/3).
 
@@ -669,3 +669,8 @@ rotate_handler(Handler) ->
 
 rotate_handler(Handler, Sink) ->
     gen_event:call(Sink, Handler, rotate, ?ROTATE_TIMEOUT).
+
+%% @private
+trace_func({Pid, Level}=FuncState, Event, ProcState) ->
+    lager:log(Level, Pid, "TRACE ~p ~p", [Event, ProcState]),
+    FuncState.