Metronome
=====

A simple library to add instrumentation to your Erlang code. This is a more
dynamic way of doing `timer:tc/3` or even a lazier version of it.

Stopwatch will measure runtime of parts of your code and calls a method on your
predefined module with the results. For example, if you compile your code with
`{d, 'stopwatch_callback_mod', 'sample_callback'}` and run the following:

```erlang
-include_lib("metronome/include/metronome.hrl").

?timed(total_sum,
  begin
    ?timed(sum_1, First = lists:sum(lists:seq(0, 100))),
    ?timed(sum_2, Second = lists:sum(lists:seq(0, 100))),
    _ = First + Second
  end).
```

You will see 3 calls to `sample_callback` module:
```erlang
sample_callback:tick(sum_1, Microseconds).
sample_callback:tick(sum_2, Microseconds).
sample_callback:tick(total_sum, Microseconds).
```
If you don't want to use the macros or if they are giving you trouble, you can
also explicitly add the start/stop points. The above code can be written like below
with no difference in execution:

```erlang
{stopwatch_start, total_sum},

{stopwatch_start, sum_1},
First = lists:sum(lists:seq(0, 100)),
{stopwatch_stop},

{stopwatch_start, sum_2},
Second = lists:sum(lists:seq(0, 100)),
{stopwatch_stop},

_ = First + Second,

{stopwatch_stop}.
```

### Usage
1. Add the package to your rebar.config
   ```erlang
   {deps, [
      {metronome, "0.1.0"}
   ]}.
   ```

2. Add the parse transform to your rebar.config
   ```erlang
   {erl_opts, [
     {parse_transform, stopwatch_transform}
   ]}.
   ```

3. [Optional] Configure a custom callback module by using overrides:
   ```erlang
   {overrides, [
     {override, metronome, [
       {erl_opts, [
         {d, 'metronome_callback_mod', 'my_sample_mod'
       }]
     }]}
   ]}.
   ```

4. Instrument your code:
   ```erlang
   {stopwatch_start, some_name},
     --- Intensive amount of work ---
   {stopwatch_stop}.
   ```
   or use the included macro:

   ```erlang
   -include_lib("metronome/include/metronome.hrl").

   ?timed(some_name,
     --- Intensive amount of work ---
    ).
   ```
### Why
I really wanted to learn more about parse transforms and also make my own life
easier. I usually mix this library with [statsderl](https://github.com/lpgauth/statsderl)
to make things really easy to report timing of different parts of my code.

### Custom callback
If you want a customized callback versus the provided one, you have to create a
module that implements the `metronome_callback` behavior. An example using `statsderl`
would look like this:

```erlang
-module(metronome_statsderl).

metronome_callback).

-export([
  tick/2
]).

tick(Name, Microseconds) ->
  statsderl:timing(atom_to_list(Name), Microseconds, 1).

```