Histogrex

v0.0.5

Histogrex v0.0.5 Histogrex View Source

High Dynamic Range (HDR) Histogram allows the recording of values across a configurable range at a configurable precision.

Storage requirement is fixed (and depends on how the histogram is configured). All functions are fully executed within the calling process (not serialized through a single process) as the data is stored within write-optimized ETS table. Each recording consists of as single call to :ets.update_counter.

Read operations consiste of a single :ets.lookup and are subsequently processed on that copy of the data (again, within the calling process).

The fist step involves creating a registry:

defmodule MyApp.Stats do

use Histogrex

histogrex :load_user, min: 1, max: 10_000_000, precision: 3
histogrex :db_save_settings, min: 1, max: 10_000, precision: 2
...

end

And then adding this module as a worker to your application’s supervisor tree:

worker(MyApp.Stats, [])

You can then record values and make queries:

alias MyApp.Stats

Stats.record!(:load_user, 233)
Stats.record!(:db_save_settings, 84)

Stats.mean(:load_user)
Stats.max(:db_save_settings)
Stats.total_count(:db_save_settings)
Stats.value_at_quantile(:load_user, 99.9)

Link to this section Summary

Types

t()

Functions

delete(h)

Deletes the histogram. The histogram can no longer be used

delete(h, metric)

Deletes the histogram. Since this histogram was dynamically created through a template, you can safely continue using it

histogrex(name, opts)

registers the histogram

lowest_equivalent_value(h, value)
lowest_equivalent_value(h, bucket_index, sub_bucket_index)
new(name, registrar, min, max, precision \\ 3, template \\ false)

Creates a new histogrex object. Note that this only creates the configuration structure. It does not create the underlying ets table/entries. There should be no need to call this direction. Use the histogrex macro instead

record(err, value, n)

Records the value n times where n defaults to 1. Return :ok on success or {:error, message} on failure. A larger than the ‘max’ specified when the histogram was created will cause an error. This is usually not called directly, but rather through the record/3 of your custom registry

record(err, metric, value, n)

Records the value n times where n defaults to 1. Uses the template to create the histogram if it doesn’t already exist. Return :ok on success or {:error, message} on failure. A larger than the ‘max’ specified when the histogram was created will cause an error. This is usually not called directly, but rather through the record/3 of your custom registry

record!(h, value, n)

Same as record/3 but raises on error

record!(template, metric, value, n)

Same as record_template/4 but raises on error

reduce(module, acc, fun)

Reduce all of a registry’s histograms

reset(h)

Resets the histogram to 0 values using an iterator. It is safe to reset an iterator during a reduce

reset(h, metric)

Resets the histogram to 0 values for the templated historam. Note that the histogram is a fixed-size, so calling this won’t free any memory

template(name, opts)
value_at_quantile(h, q)

Gets the value at the requested quantile using the given iterator. When doing multiple calculations, it is slightly more efficent to first recreate and then re-use an iterator (plus the values will consistently be calculated based on the same data). Iterators are automatically reset before each call

value_at_quantile(h, metric, q)

Gets the value at the requested quantile for the templated histogram

Link to this section Types

Link to this type t() View Source 
t() :: %Histogrex{bucket_count: pos_integer, counts_length: pos_integer, name: atom | binary, registrar: module, sub_bucket_count: non_neg_integer, sub_bucket_half_count: non_neg_integer, sub_bucket_half_count_magnitude: non_neg_integer, sub_bucket_mask: non_neg_integer, template: nil | tuple, unit_magnitude: non_neg_integer}

Link to this section Functions

Link to this function delete(h) View Source 
delete(t) :: :ok

Deletes the histogram. The histogram can no longer be used.

Link to this function delete(h, metric) View Source 
delete(t, atom | binary) :: :ok

Deletes the histogram. Since this histogram was dynamically created through a template, you can safely continue using it.

Link to this macro histogrex(name, opts) View Source (macro)

registers the histogram

A min, max and precision must be supplied. min and max represent the minimal and maximal expected values. For example, if you’re looking to measure how long a database call took, you could specify: min: 1, max: 10_000 and provide time in millisecond, thus allowing you to capture values from 1ms to 10sec.

min must be greater than 0. max must be greater than min. precision must be between 1 and 5 (inclusive).

Examples 

histogrex :user_list, min: 1, max: 10000000, precision: 3
Link to this function lowest_equivalent_value(h, value) View Source
Link to this function lowest_equivalent_value(h, bucket_index, sub_bucket_index) View Source
Link to this function new(name, registrar, min, max, precision \\ 3, template \\ false) View Source 
new(binary | atom, module, pos_integer, pos_integer, 1..5, boolean) :: t

Creates a new histogrex object. Note that this only creates the configuration structure. It does not create the underlying ets table/entries. There should be no need to call this direction. Use the histogrex macro instead.

Link to this function record(err, value, n) View Source 
record(t | {:error, any}, pos_integer, pos_integer) ::
  :ok |
  {:error, any}

Records the value n times where n defaults to 1. Return :ok on success or {:error, message} on failure. A larger than the ‘max’ specified when the histogram was created will cause an error. This is usually not called directly, but rather through the record/3 of your custom registry

Link to this function record(err, metric, value, n) View Source 
record(t | {:error, any}, atom | binary, pos_integer, pos_integer) ::
  :ok |
  {:error, any}

Records the value n times where n defaults to 1. Uses the template to create the histogram if it doesn’t already exist. Return :ok on success or {:error, message} on failure. A larger than the ‘max’ specified when the histogram was created will cause an error. This is usually not called directly, but rather through the record/3 of your custom registry

Link to this function record!(h, value, n) View Source 
record!(t, pos_integer, pos_integer) :: :ok | no_return

Same as record/3 but raises on error

Link to this function record!(template, metric, value, n) View Source 
record!(t, atom | binary, pos_integer, pos_integer) ::
  :ok |
  no_return

Same as record_template/4 but raises on error

Link to this function reduce(module, acc, fun) View Source 
reduce(module, any, (Histogrex.Iterator.t, any -> any)) :: any

Reduce all of a registry’s histograms

Link to this function reset(h) View Source 
reset(t | Histogrex.Iterator.t) :: :ok

Resets the histogram to 0 values using an iterator. It is safe to reset an iterator during a reduce.

Link to this function reset(h, metric) View Source 
reset(t, atom | binary) :: :ok

Resets the histogram to 0 values for the templated historam. Note that the histogram is a fixed-size, so calling this won’t free any memory.

Link to this macro template(name, opts) View Source (macro)
Link to this function value_at_quantile(h, q) View Source 
value_at_quantile(t | Histogrex.Iterator.t, float) :: float

Gets the value at the requested quantile using the given iterator. When doing multiple calculations, it is slightly more efficent to first recreate and then re-use an iterator (plus the values will consistently be calculated based on the same data). Iterators are automatically reset before each call.

Link to this function value_at_quantile(h, metric, q) View Source 
value_at_quantile(t, atom, float) :: float

Gets the value at the requested quantile for the templated histogram