README.md

ale

ale, a lager extension, makes it possible for several processes to trace the same modules.

Dependencies

To build ale you will need a working installation of Erlang R15B (or later).
Information on building and installing Erlang/OTP can be found here (more info).

ale is built using rebar that can be found here, with building instructions here. rebar's dynamic configuration mechanism, described here, is used so the environment variable REBAR_DEPS should be set to the directory where your erlang applications are located.

ale also requires lager to be installed.

Downloading

Clone the repository in a suitable location:

$ git clone git://github.com/tonyrog/ale.git

Functionality

Concepts

ale extends lager by using a server that keeps track of all trace request thus making it possible for several processes to add the same traces while only adding one to lager and likewise not removing it from lager until all processes have removed it.
Available api is:

• trace(on | off, ModuleOrPidOrFilter::atom() | pid() | tuple() | list(tuple)), Loglevel::atom()) - prints trace output on console as long as calling process hasn't terminated.
• trace(on | off, ModuleOrPidOrFilter::atom() | pid() | tuple() | list(tuple)), Loglevel::atom(), File::string()) - prints trace output to File as long as calling process hasn't terminated.
• trace_gl(on | off, ModuleOrPidOrFilter::atom() | pid() | tuple() | list(tuple)), Loglevel::atom()) - prints trace output on console as long as calling process' group leader hasn't terminated. Suitable for calls from a shell.
• trace_gl(on | off, ModuleOrPidOrFilter::atom() | pid() | tuple() | list(tuple)), Loglevel::atom(), File::string()) - prints trace output to File as long as calling process' group leader hasn't terminated. Suitable for calls from a shell.
• trace_file() - returns the default trace file.
• trace_file(File::string()) - sets the default trace file.

Filter is a tuple {tag, Tag} that lager uses to determine what to output.
LogLevel is debug | info | notice | warning | error | critical | alert | emergency.
File is relative to lagers log_root if given.
See lager documentations for more details.
Examples:
``` ale:trace(on, sz_master, debug). ale:trace(on, self(), debug). ale:trace_gl(on, sz_node, info, "/tmp/ale.log"). ale:trace(off, sz_master, debug). ale:trace(on, [{module, ale}, {function, start}], debug). ```

There are also some shortcut functions:

• debug(ModuleOrPidOrList::atom() | pid() | tuple() | list(atom())) - calls trace(on, ModuleOrPidOrList, debug).
• info(ModuleOrPidOrList::atom() | pid() | tuple() | list(atom())) - calls trace(on, ModuleOrPidOrList, info).
• warning(ModuleOrPidOrList::atom() | pid() | tuple() | list(atom())) - calls trace(on, ModuleOrPidOrList, warning).
• error(ModuleOrPidOrList::atom() | pid() | tuple() | list(atom())) - calls trace(on, ModuleOrPidOrList, error).
• xxx_gl(ModuleOrPidOrList::atom() | pid() | tuple() | list(atom())) - calls trace_gl(on, ModuleOrPidOrList, xxx) for xxx = debug | info | error | warning.
• xxx(ModuleOrPidOrList::atom() | pid() | tuple() | list(atom()), File::string()) - calls trace(on, ModuleOrPidOrList, xxx, File) for xxx = debug | info | error | warning.
• xxx_gl(ModuleOrPidOrList::atom() | pid() | tuple() | list(atom()), File::string()) - calls trace_gl(on, ModuleOrPidOrList, xxx, File) for xxx = debug | info | error | warning.
• xxxf(ModuleOrPidOrList::atom() | pid() | tuple() | list(atom())) - calls trace(on, ModuleOrPidOrList, xxx, default) for xxx = debug | info | error | warning. Default trace file can be set using trace_file/1.
• xxxf_gl(ModuleOrPidOrList::atom() | pid() | tuple() | list(atom())) - calls trace_gl(on, ModuleOrPidOrList, xxx, default) for xxx = debug | info | error | warning. Default trace file can be set using trace_file/1.

These can be called with lists of modules.

Config Files

Arguments to all applicable erlang applications are specified in an erlang configuration file.
Traces can be added to the ale part of the configuration file. These traces will be active as long as ale i running.
Example:

	{traces, [
	          {[{module, sz_master}], debug}, 
		  {[{module, sz_node}], info, "/tmp/ale.log"}
		 ]}

An example can be found in "sys.config".

Tips

If you start tracing using the non-groupleader function calls from the shell you can stop it by 'crashing' the shell, for ex with a=b. Might be handy if you get more output than expected ;-)

Building

Rebar will compile all needed dependencies.
Compile:

$ cd ale
$ rebar compile
...
==> ale (compile)

Running

There is a quick way to run the application for testing:

$ erl -sname ale -config sys -pa <path>/ale/ebin
>ale:start().

(Instead of specifing the path to the ebin directory you can set the environment ERL_LIBS.)

Stop:

>halt().

Release

To generate a proper release follow the instructions in Release Handling or look in the Rebar tutorial.

Before the last step you have to update the file "ale/rel/files/sys.config" with your own settings. You probably also have to update "ale/rel/reltool.config" with the correct path to your application (normally "{lib_dirs, ["../.."]}") and all apps you need.

       {app, sasl,   [{incl_cond, include}]},
       {app, stdlib, [{incl_cond, include}]},
       {app, kernel, [{incl_cond, include}]},
       {app, lager, [{incl_cond, include}]}
       {app, ale, [{incl_cond, include}]}

And then you run:

$ rebar generate

Before generating a new version of a release the old version should be (re)moved.

Start node:

$ cd rel
$ ale/bin/ale start

(If you want to have access to the erlang node use console instead of start.)

Documentation

ale is documented using edoc. To generate the documentation do:

$ cd ale
$ rebar doc

You get the resulting html-files in ale/doc subdirectory.