Elixometer
==========
[![Build Status](https://travis-ci.org/pinterest/elixometer.svg?branch=master)](https://travis-ci.org/pinterest/elixometer)
[![Coverage Status](https://coveralls.io/repos/pinterest/elixometer/badge.svg?branch=&service=github)](https://coveralls.io/github/pinterest/elixometer?branch=master)
A light wrapper around exometer.
Elixometer allows you to define metrics and subscribe them automatically
to the default reporter for your environment.
## Installation
Add the following to your dependencies in mix.exs:
```elixir
{:elixometer, github: "pinterest/elixometer"}
```
Then, add `:elixometer` to your applications. That's it!
## Configuration
In one of your config files, set up an exometer reporter, and then register
it to elixometer like this:
```elixir
config(:exometer_core, report: [reporters: [{:exometer_report_tty, []}]])
config(:elixometer, reporter: :exometer_report_tty,
env: Mix.env,
metric_prefix: "myapp")
```
Metrics are prepended with the `metric_prefix`, the type of metric and the environment name.
The optional `update_frequency` key of the :elixometer config controls the interval between reports. By default this is set to `1000` ms in the `dev` environment and `20` ms in the `test` environment.
## Metrics
Defining metrics in elixometer is substantially easier than in exometer. Instead of defining and then updating a metric, just update it. Also, instead of providing a list of atoms, a metric is named with a period separated bitstring. Presently, Elixometer supports timers, histograms, gauges, counters, and spirals.
Timings may also be defined by annotating a function with a @timed annotation. This annotation takes a key argument, which tells elixometer what key to use. You can specify `:auto` and a key will be generated from the module name and method name.
Updating a metric is similarly easy:
```elixir
defmodule ParentModule.MetricsTest do
use Elixometer
# Updating a counter
def counter_test(thingie) do
update_counter("metrics_test.\#{thingie}.count", 1)
end
# Updating a spiral
def spiral_test(thingie) do
update_spiral("metrics_test.\#{thingie}.qps", 1)
end
# Timing a block of code in a function
def timer_test do
timed("metrics_test.timer_test.timings") do
OtherModule.slow_method
end
end
# Timing a function. The metric name will be [:timed, :function]
@timed(key: "timed.function") # key will be: prefix.dev.timers.timed.function
def function_that_is_timed do
OtherModule.slow_method
end
# Timing a function with an auto generated key
# The key will be "<prefix>.<env>.timers.parent_module.metrics_test.another_timed_function"
# If the env is prod, the environment is omitted from the key
@timed(key: :auto)
def another_timed_function do
OtherModule.slow_method
end
end
```
## Additional Reporters
By default, Elixometer only includes the `exometer_core` package. However, some reporters (namely OpenTSDB and Statsd) are only available by installing `exometer`. This is fairly easy to do, all you need to do is update your `mix.exs` to include exometer as a dependency and start it as an application. For example:
```elixir
def application do
[
applications: [:exometer,
... other applications go here
],
...
]
end
defp deps do
[
{:exometer, github: "PSPDFKit-labs/exometer_core"}
]
end
```