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"]
  
  StatsAgg.retrieve_stats(all_stats_query)
  StatsAgg.retrieve_stats(group_only_query)
  StatsAgg.retrieve_stats(group_and_module_query)
  StatsAgg.retrieve_stats(group_module_and_function_query)

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"}
  ]
end

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)
  end  
end

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 https://hexdocs.pm/stats_agg.