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.

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. File must exist.
• 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. File must exist.

Filter is a tuple {tag, Tag} that lager uses to determine what to output.
LogLevel is debug | info | notice | warning | error | critical | alert | emergency.
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).


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:
{init_traces, [
{[{module, sz_master}], debug},
{[{module, sz_node}], info, "/tmp/ale.log"}
]}


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

Tips

If you start traceing 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

.

When generating a new release the old has to 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