Parse Transform Support

The Parse Transform Support Library provides additional support for putting additional (and hopefully useful) information in your log statements without harassing your fingers.

To use the library, its fastlog_parse_trans module must be available at build time, and your module must include an alternative header file. This header automatically includes the default fastlog.hrl header, and so you do not need to include it yourself. A real-world example is probably a good idea at this point.

-module(dxkit_event_bridge).
%% other module attributes omitted for brevity 
-include_lib("fastlog_parse_trans/include/fastlog.hrl").

permanent_subscriber(Handler, Args) ->
    ?DEBUG("Starting Handler ~p~n", [Handler]),
    supervisor:start_child(?MODULE, [Handler, Args]).

When this logging statement is evaluated, assuming that there is a logger that will match the right category and level, we should see a log statement something like this:

['[email protected]'] [<0.127.0>] [info] [dxkit_event_handler_bridge] [start_link] [line:50] Starting Handler dxweb_event_handler

As you can see, the parse transform has added a lot of additional data. Let's take a look at how it works.

How it works

The parse transform looks for remote (i.e., external) calls to logging API functions in the fastlog module. When such calls are detected, if they are already passing a log record, they are ignored. Otherwise, the following steps take place.

1. the destination (logger/category), message and (optional) argument list are extracted
2. a log record is constructed, using existing constants and any variables in scope for the current function
3. a context record is constructed and initialised with the context of the current call (more on this later)
4. the call-site is replaced with a call to fastlog:<function>/1, passing the now generated log record

Naturally these changes are made to the AST prior to compilation, and therefore will be evaluated at runtime as though they were originally written in to the module's source code. In particular, the enrichment of the context record includes the current node, process id, module name, function name, function arity and line number. The first two are produced by injecting a call to the relevant BIF, the latter ones injected during transformation of the AST and therefore statically compiled into the module.

Controlling Logging Output

The choice of which fields (in the log and/or context records) are populated isn't available at this time. The choice of which fields should appear in generated logs however, can be controlled on a per-logger basis using the pattern configuration element - see Configuring Fastlog for further details on pattern use.