diff --git a/src/error_logger_lager_h.erl b/src/error_logger_lager_h.erl index 3b5af1c..19db309 100644 --- a/src/error_logger_lager_h.erl +++ b/src/error_logger_lager_h.erl @@ -14,6 +14,13 @@ %% specific language governing permissions and limitations %% under the License. +%% @doc A error_logger backend for redirecting events into lager. +%% Error messages and crash logs are also optionally written to a crash log. + +%% @see lager_crash_log + +%% @private + -module(error_logger_lager_h). -behaviour(gen_event). diff --git a/src/lager.erl b/src/lager.erl index 7f44c23..68b351a 100644 --- a/src/lager.erl +++ b/src/lager.erl @@ -14,6 +14,8 @@ %% specific language governing permissions and limitations %% under the License. +%% @doc The lager logging framework. + -module(lager). %% API @@ -24,6 +26,8 @@ %% API +%% @doc Start the application. Mainly useful for using `-s lager' as a command +%% line switch to the VM to make lager start on boot. start() -> start(lager). start(App) -> @@ -37,6 +41,7 @@ start_ok(App, {error, {not_started, Dep}}) -> start_ok(App, {error, Reason}) -> erlang:error({app_start_failed, App, Reason}). +%% @private log(Level, Module, Function, Line, Pid, Time, Message) -> Timestamp = lager_util:format_time(Time), Msg = [io_lib:format("[~p] ~p@~p:~p:~p ", [Level, Pid, Module, @@ -44,6 +49,7 @@ log(Level, Module, Function, Line, Pid, Time, Message) -> gen_event:sync_notify(lager_event, {log, lager_util:level_to_num(Level), Timestamp, Msg}). +%% @private log(Level, Module, Function, Line, Pid, Time, Format, Args) -> Timestamp = lager_util:format_time(Time), Msg = [io_lib:format("[~p] ~p@~p:~p:~p ", [Level, Pid, Module, @@ -51,18 +57,21 @@ log(Level, Module, Function, Line, Pid, Time, Format, Args) -> gen_event:sync_notify(lager_event, {log, lager_util:level_to_num(Level), Timestamp, Msg}). +%% @doc Manually log a message into lager without using the parse transform. log(Level, Pid, Message) -> Timestamp = lager_util:format_time(), Msg = [io_lib:format("[~p] ~p ", [Level, Pid]), Message], gen_event:sync_notify(lager_event, {log, lager_util:level_to_num(Level), Timestamp, Msg}). +%% @doc Manually log a message into lager without using the parse transform. log(Level, Pid, Format, Args) -> Timestamp = lager_util:format_time(), Msg = [io_lib:format("[~p] ~p ", [Level, Pid]), io_lib:format(Format, Args)], gen_event:sync_notify(lager_event, {log, lager_util:level_to_num(Level), Timestamp, Msg}). +%% @doc Set the loglevel for a particular backend. set_loglevel(Handler, Level) when is_atom(Level) -> Reply = gen_event:call(lager_event, Handler, {set_loglevel, Level}), %% recalculate min log level @@ -70,6 +79,8 @@ set_loglevel(Handler, Level) when is_atom(Level) -> lager_mochiglobal:put(loglevel, MinLog), Reply. +%% @doc Set the loglevel for a particular backend that has multiple identifiers +%% (eg. the file backend). set_loglevel(Handler, Ident, Level) when is_atom(Level) -> Reply = gen_event:call(lager_event, Handler, {set_loglevel, Ident, Level}), %% recalculate min log level @@ -77,6 +88,8 @@ set_loglevel(Handler, Ident, Level) when is_atom(Level) -> lager_mochiglobal:put(loglevel, MinLog), Reply. +%% @doc Get the loglevel for a particular backend. In the case that the backend +%% has multiple identifiers, the lowest is returned get_loglevel(Handler) -> case gen_event:call(lager_event, Handler, get_loglevel) of X when is_integer(X) -> @@ -84,10 +97,12 @@ get_loglevel(Handler) -> Y -> Y end. +%% @private get_loglevels() -> [gen_event:call(lager_event, Handler, get_loglevel) || Handler <- gen_event:which_handlers(lager_event)]. +%% @private minimum_loglevel([]) -> 9; %% higher than any log level, logging off minimum_loglevel(Levels) -> diff --git a/src/lager_app.erl b/src/lager_app.erl index 20d3645..6acdd5e 100644 --- a/src/lager_app.erl +++ b/src/lager_app.erl @@ -14,6 +14,10 @@ %% specific language governing permissions and limitations %% under the License. +%% @doc Lager's application module. Not a lot to see here. + +%% @private + -module(lager_app). -behaviour(application). diff --git a/src/lager_console_backend.erl b/src/lager_console_backend.erl index 3af2991..68b263d 100644 --- a/src/lager_console_backend.erl +++ b/src/lager_console_backend.erl @@ -14,6 +14,9 @@ %% specific language governing permissions and limitations %% under the License. +%% @doc Console backend for lager. Configured with a single option, the loglevel +%% desired. + -module(lager_console_backend). -behaviour(gen_event). @@ -23,9 +26,11 @@ -record(state, {level}). +%% @private init(Level) -> {ok, #state{level=lager_util:level_to_num(Level)}}. +%% @private handle_call(get_loglevel, #state{level=Level} = State) -> {ok, Level, State}; handle_call({set_loglevel, Level}, State) -> @@ -33,17 +38,21 @@ handle_call({set_loglevel, Level}, State) -> handle_call(_Request, State) -> {ok, ok, State}. +%% @private handle_event({log, Level, Time, Message}, #state{level=LogLevel} = State) when Level >= LogLevel -> io:put_chars([Time, " ", Message, "\n"]), {ok, State}; handle_event(_Event, State) -> {ok, State}. +%% @private handle_info(_Info, State) -> {ok, State}. +%% @private terminate(_Reason, _State) -> ok. +%% @private code_change(_OldVsn, State, _Extra) -> {ok, State}. diff --git a/src/lager_crash_log.erl b/src/lager_crash_log.erl index e55dc98..56ea270 100644 --- a/src/lager_crash_log.erl +++ b/src/lager_crash_log.erl @@ -14,6 +14,12 @@ %% specific language governing permissions and limitations %% under the License. +%% @doc Lager crash log writer. This module implements a gen_server which writes +%% error_logger error messages out to a file in their original format. The +%% location to which it logs is configured by the environment var `crash_log'. +%% Omitting this variable disables crash logging. Crash logs are printed safely +%% using trunc_io via code mostly lifted from riak_err. + -module(lager_crash_log). -behaviour(gen_server). @@ -39,12 +45,15 @@ _ -> ok end). +%% @private start_link(Filename) -> gen_server:start_link({local, ?MODULE}, ?MODULE, [Filename], []). +%% @private start(Filename) -> gen_server:start({local, ?MODULE}, ?MODULE, [Filename], []). +%% @private init([Filename]) -> case lager_util:open_logfile(Filename, false) of {ok, {FD, Inode}} -> @@ -53,9 +62,11 @@ init([Filename]) -> Error end. +%% @private handle_call(_Call, _From, State) -> {reply, ok, State}. +%% @private handle_cast({log, Event}, #state{name=Name, fd=FD, inode=Inode, flap=Flap} = State) -> FmtMaxBytes = 1024, TermMaxSize = 500, @@ -101,12 +112,15 @@ handle_cast({log, Event}, #state{name=Name, fd=FD, inode=Inode, flap=Flap} = Sta handle_cast(_Request, State) -> {noreply, State}. +%% @private handle_info(_Info, State) -> {noreply, State}. +%% @private terminate(_Reason, _State) -> ok. +%% @private code_change(_OldVsn, State, _Extra) -> {ok, State}. diff --git a/src/lager_file_backend.erl b/src/lager_file_backend.erl index 0f413b0..15d39f6 100644 --- a/src/lager_file_backend.erl +++ b/src/lager_file_backend.erl @@ -14,6 +14,12 @@ %% specific language governing permissions and limitations %% under the License. +%% @doc File backend for lager, with multiple file support. +%% Multiple files are supported, each with the path and the loglevel being +%% configurable. The configuration paramter for this backend is a list of +%% 2-tuples of the form `{FileName, Level}'. This backend supports external log +%% rotation and will re-open handles to files if the inode changes. + -module(lager_file_backend). -behaviour(gen_event). @@ -47,7 +53,7 @@ _ -> ok end). - +%% @private init(LogFiles) -> Files = [begin case lager_util:open_logfile(Name, true) of @@ -62,6 +68,7 @@ init(LogFiles) -> {Name, Level} <- LogFiles], {ok, #state{files=Files}}. +%% @private handle_call({set_loglevel, _}, State) -> {ok, {error, missing_identifier}, State}; handle_call({set_loglevel, Ident, Level}, #state{files=Files} = State) -> @@ -86,6 +93,7 @@ handle_call(get_loglevel, #state{files=Files} = State) -> handle_call(_Request, State) -> {ok, ok, State}. +%% @private handle_event({log, Level, Time, Message}, #state{files=Files} = State) -> NewFiles = lists:map( fun(#file{level=L} = File) when Level >= L -> @@ -97,9 +105,11 @@ handle_event({log, Level, Time, Message}, #state{files=Files} = State) -> handle_event(_Event, State) -> {ok, State}. +%% @private handle_info(_Info, State) -> {ok, State}. +%% @private terminate(_Reason, State) -> %% flush and close any file handles lists:foreach( @@ -107,6 +117,7 @@ terminate(_Reason, State) -> (_) -> ok end, State#state.files). +%% @private code_change(_OldVsn, State, _Extra) -> {ok, State}. diff --git a/src/lager_handler_watcher.erl b/src/lager_handler_watcher.erl index 41e2c35..758ed9d 100644 --- a/src/lager_handler_watcher.erl +++ b/src/lager_handler_watcher.erl @@ -1,3 +1,24 @@ +%% Copyright (c) 2011 Basho Technologies, Inc. All Rights Reserved. +%% +%% This file is provided to you under the Apache License, +%% Version 2.0 (the "License"); you may not use this file +%% except in compliance with the License. You may obtain +%% a copy of the License at +%% +%% http://www.apache.org/licenses/LICENSE-2.0 +%% +%% Unless required by applicable law or agreed to in writing, +%% software distributed under the License is distributed on an +%% "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +%% KIND, either express or implied. See the License for the +%% specific language governing permissions and limitations +%% under the License. + +%% @doc A process that does a gen_event:add_sup_handler and attempts to re-add +%% event handlers when they exit. + +%% @private + -module(lager_handler_watcher). -behaviour(gen_server). diff --git a/src/lager_handler_watcher_sup.erl b/src/lager_handler_watcher_sup.erl index 0b43861..9243619 100644 --- a/src/lager_handler_watcher_sup.erl +++ b/src/lager_handler_watcher_sup.erl @@ -14,6 +14,10 @@ %% specific language governing permissions and limitations %% under the License. +%% @doc A supervisor for monitoring lager_handler_watcher processes. + +%% @private + -module(lager_handler_watcher_sup). -behaviour(supervisor). diff --git a/src/lager_sup.erl b/src/lager_sup.erl index 9efc3e8..acdab76 100644 --- a/src/lager_sup.erl +++ b/src/lager_sup.erl @@ -14,6 +14,10 @@ %% specific language governing permissions and limitations %% under the License. +%% @doc Lager's top level supervisor. + +%% @private + -module(lager_sup). -behaviour(supervisor). diff --git a/src/lager_transform.erl b/src/lager_transform.erl index 451bb21..c575ac5 100644 --- a/src/lager_transform.erl +++ b/src/lager_transform.erl @@ -14,18 +14,20 @@ %% specific language governing permissions and limitations %% under the License. +%% @doc The parse transform used for lager messages. +%% This parse transform rewrites functions calls to lager:Severity/1,2 into +%% a more complicated function that captures module, function, line, pid and +%% time as well. The entire function call is then wrapped in a case that +%% checks the mochiglobal 'loglevel' value, so the code isn't executed if +%% nothing wishes to consume the message. + -module(lager_transform). -export([parse_transform/2]). -define(LEVELS, [debug, info, notice, warning, error, critical, alert, emergency]). -%% This parse transform rewrites functions calls to lager:Severity/1,2 into -%% a more complicated function that captures module, function, line, pid and -%% time as well. The entire function call is then wrapped in a case that -%$ checks the mochiglobal 'loglevel' value, so the code isn't executed if -%% nothing wishes to consume the message. - +%% @private parse_transform(AST, _Options) -> %io:format("~n~p~n", [AST]), walk_ast([], AST).