exmetrics
This elixir project is inspired by the excellent codahale/metrics library.
It provides counters, gauges and histograms for instrumenting an elixir application.
Usage
Counters
# Increment a counter
iex> Metrics.Counter.incr "my_counter"
:ok
iex> Metrics.Counter.get "my_counter"
1
# Add to a counter
iex> Metrics.Counter.add "my_counter", 5
:ok
iex> Metrics.Counter.get "my_counter"
6
# Reset a counter
iex> Metrics.Counter.reset "my_counter"
:ok
iex> Metrics.Counter.get "my_counter"
0
Gauges
# Set gauge to a value
iex> Metrics.Gauge.set "my_gauge", 10
:ok
# or
# Set gauge to a function which is lazily evaluated
iex> Metrics.Gauge.set "my_gauge", fn -> 10 end
# Get value of a gauge
iex> Metrics.Gauge.get "my_gauge"
10
# Remove gauge
iex> Metrics.Gauge.remove "my_gauge"
:ok
iex> Metrics.Gauge.get "my_gauge"
nil
Histograms
See hdr_histogram_erl for semantics.
# Create a new histogram with max value 1000000 and 3 significant figures precision
iex> Metrics.Histogram.new "my_histogram", 1000000, 3
:ok
# This automatically registers gauges for the histogram's
# 50th percentile
# 75th percentile
# 90th percentile
# 95th percentile
# 99th percentile
# 99.9th percentile
# Max histogram value
# Min histogram value
# Standard deviation
# Total count
# Record a value inside a histogram
iex> Metrics.Histogram.record "my_histogram", 100
:ok
iex> Enum.each 0..100, &(Metrics.Histogram.record "my_histogram", &1)
# Get a snapshot of all data
iex> Metrics.snapshot
%{counters: %{},
gauges: %{"my_histogram.Count" => 102, "my_histogram.Max" => 100,
"my_histogram.Mean" => 50.5, "my_histogram.Min" => 0,
"my_histogram.P50" => 50.0, "my_histogram.P75" => 76.0,
"my_histogram.P90" => 91.0, "my_histogram.P95" => 96.0,
"my_histogram.P99" => 100.0, "my_histogram.P999" => 100.0,
"my_histogram.Stddev" => 29.4}}
# Remove a histogram
iex> Metrics.Histogram.remove "my_histogram"
:ok
Benchmark
The benchmarks were performed on a MacBook Pro (13 Zoll, Mid 2012), with 8 GB 1600 MHz DDR3 RAM. You can repeat them with
git clone https://github.com/fourcube/exmetrics.git; cd exmetrics
mix deps.get
mix bench
Results
## Exmetrics.Bench
Exmetrics.record/2 1000000 1.21 µs/op
Exmetrics.Counter.incr/1 1000000 1.37 µs/op
Exmetrics.Counter.add/2 1000000 1.50 µs/op
Exmetrics.Gauge.set/2 1000000 1.57 µs/op
Exmetrics.Counter.get/1 500000 5.70 µs/op
Exmetrics.Gauge.get/1 500000 6.03 µs/op
Exmetrics.snapshot/0 - 1 histogram 20000 102.50 µs/op
Exmetrics.Histogram.new/3 10000 358.51 µs/op
Exmetrics.snapshot/0 - 10 histograms 1000 1033.07 µs/op
Exmetrics.snapshot/0 - 100 histograms 100 10444.18 µs/op
Installation
If available in Hex, the package can be installed as:
Add exmetrics and hdr_histogram to your list of dependencies in
mix.exs
:def deps do [ {:exmetrics, "~> 1.0"}, {:hdr_histogram, git: "https://github.com/HdrHistogram/hdr_histogram_erl.git", tag: "0.2.6"} ] end
Ensure exmetrics is started before your application:
def application do [applications: [:exmetrics]] end