# StatsAgg

StatsAgg is a library that allows instrumentation of Elixir functions to track durations.

## Overview 

StatsAgg defines a macro, `with_stats_agg`, that makes it simple to add this instrumentation to your projects.

StatsAgg instrumentation includes a customizable `group` to allow related stats, or stats you wish to
display on an Information Radiator to be easily accessible.

StatsAgg is implemented as a GenServer so calls to record durations are asynchronous. Only the durations are stored
for each method to help reduce memory requirements. The durations are stored as a nested map with the keys:

 - `group`: an arbitrary name provided by you, defaults to _main_
 - `module`: the name of the module as returned by `__MODULE__`
 - `function`: the name of the function, in the form: _name/arity_

## Basic Usage

StatsAgg calculates and returns the accumulated stats via a call to the `StatsAgg.retrieve_stats/1` method. Stats
can be retrieved at each level of the hierarchy. Thus you can query as in the following examples:

  all_stats_query = []
  group_only_query = ["main"]
  group_and_module_query = ["main", "MyModule"]
  group_module_and_function_query = ["main", "MyModule", "function/0"]

The results are a list of Maps with the following shape:

    avg_duration: 17, 
    durations: [14, 17, 21],
    function: "function/0", 
    group: "main",
    max_duration: 21, 
    min_duration: 14, 
    module: "MyModule",
    most_recent_duration: 14

## Considerations

Being a GenServer module, StatsAgg will lose history if the app is shutdown or restarted. 

## Installation

If [available in Hex](, the package can be installed
by adding `stats_agg` to your list of dependencies in `mix.exs`:

def deps do
    {:stats_agg, "~> 0.1.0"}

Add `StatsAgg` to your Application start:

defmodule MyApp.Application do
  use Application
  def start(_type, _args) do
    import Supervisor.Spec
    children = [
      worker(Ciroque.Monitoring.StatsAgg, [])
    opts = [strategy: :one_for_one, name: MyApp.Supervisor]
    Supervisor.start_link(children, opts)

You can then use the macros to instrument your functions, or call the `StatsAgg` functions directly.

## Miscellany

Documentation can be generated with [ExDoc](
and published on [HexDocs]( Once published, the docs can
be found at [](