README.md

# Telemetry.Metrics

[![CircleCI](https://circleci.com/gh/beam-telemetry/telemetry_metrics.svg?style=svg)](https://circleci.com/gh/beam-telemetry/telemetry_metrics)
[![Codecov](https://codecov.io/gh/beam-telemetry/telemetry_metrics/branch/master/graphs/badge.svg)](https://codecov.io/gh/beam-telemetry/telemetry_metrics/branch/master/graphs/badge.svg)

Defines data model and specifications for aggregating Telemetry events.

Telemetry.Metrics provides functions for building *metric specifications* - structs describing how
values of particular events should be aggregated. Metric specifications can be provided to a reporter
which knows how to translate the events into a metric *in the system it reports to*. This is the crucial
part of this library design - it doesn't aggregate events itself in any way, it relies on 3rd party
reporters to perform this work in a way that makes the most sense for a metrics system at hand.

To give a more concrete example, let's say that you want to count the number of database queries your
application makes, and you want a separate counter for each query type and table. In this case, you
would construct the following metric specification:

```elixir
Telemetry.Metrics.counter(
  "db.query",
  name: "db.query.count",
  tags: [:table, :query_type]
)
```

This specification means that:

* metric should count the number of times a `[:db, :query]` event has been emitted, regardless of
  event value
* the name of the metric is `[:db, :query, :count]`
* the count should be broken down by each unique `:table`/`:query_type` pair found in event metadata

Now when we provide such specification to the reporter and emit following events

```elixir
:telemetry.execute([:db, :query], 32, %{table: "users", query_type: "select"})
:telemetry.execute([:db, :query], 67, %{table: "users", query_type: "insert"})
:telemetry.execute([:db, :query], 18, %{table: "users", query_type: "select"})
:telemetry.execute([:db, :query], 15, %{table: "users", query_type: "select"})
```

we expect to find the following aggregations in the metric system we report to

| table      | query_type | count |
|------------|------------|-------|
| `users`    | `select`   | 1     |
| `users`    | `create`   | 1     |
| `products` | `select`   | 2     |

The way in which reporters aggregate or export this data is not in the scope of this project. Rather,
a goal is to define a standardized set of aggregations that will be supported by reporters.

See the documentation for [Telemetry.Metrics module](https://hexdocs.pm/telemetry_metrics/0.1.0/Telemetry.Metrics.html)
for more details.

## Copyright and License

Telemetry.Metrics is copyright (c) 2018 Chris McCord and Erlang Solutions.

Telemetry.Metrics source code is released under Apache License, Version 2.0.

See [LICENSE](LICENSE) and [NOTICE](NOTICE) files for more information.