# Statsd Metric

[![Hex.pm Version](http://img.shields.io/hexpm/v/statsd_metric.svg?style=flat)](https://hex.pm/packages/statsd_metric)
[![HexDocs](https://img.shields.io/badge/HexDocs-Yes-blue)](https://hexdocs.pm/statsd_metric)
[![Hex.pm License](http://img.shields.io/hexpm/l/statsd_metric.svg?style=flat)](https://hex.pm/packages/statsd_metric)

**A fast StatsD / DogStatsD metric encoder and single-pass parser.**

`StatsdMetric` supports all standard StatsD metric types:

* Counter
* Gauge
* Histogram
* Timer
* Set
* Meter

It also supports DogStatsD sample rates and tags.

## Installation

The package can be installed by adding `statsd_metric` to your list of
dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:statsd_metric, "~> 1.0"}
  ]
end
```

## Usage ([documentation](https://hexdocs.pm/statsd_metric))

#### Encoding Example

```elixir
iex> metric = %StatsdMetric{key: "name.spaced", value: 1.0, type: :counter}
iex> StatsdMetric.encode(metric)
["name.spaced", 58, "1.0", 124, "c"]

iex> metric = %StatsdMetric{key: "name.spaced", value: 1.0, type: :counter}
iex> StatsdMetric.encode_to_string(metric)
"name.spaced:1.0|c"
```

Directly encoding stat parameters is also supported:

```elixir
iex> StatsdMetric.encode_parts("name.spaced", 1.0, :counter)
["name.spaced", 58, "1.0", 124, "c"]

iex> StatsdMetric.encode_parts_to_string("name.spaced", 1.0, :counter)
"name.spaced:1.0|c"
```

#### Parsing Example

``` elixir
iex> StatsdMetric.decode!("name.spaced:1.0|c|@0.1|#foo:bar")
%StatsdMetric{
  key: "name.spaced",
  value: 1.0,
  type: :counter,
  sample_rate: 0.1,
  tags: %{"foo" => "bar"}
}
```

Multiple metrics separated by a newline are also supported:

``` elixir
iex> StatsdMetric.decode!("first.metric:1.0|c|@0.1|#foo:bar\\nsecond.metric:15.0|g|#foo:bar")
[
  %StatsdMetric{
    key: "first.metric",
    value: 1.0,
    type: :counter,
    sample_rate: 0.1,
    tags: %{"foo" => "bar"}
  },
  %StatsdMetric{
    key: "second.metric",
    value: 15.0,
    type: :gauge,
    tags: %{"foo" => "bar"}
  }
]
```

## License

`StatsdMetric` is released under the [`Apache License
2.0`](https://github.com/elliotekj/statsd_metric/blob/main/LICENSE).

## About

This package was written by [Elliot Jackson](https://elliotekj.com).

- Blog: [https://elliotekj.com](https://elliotekj.com)
- Email: elliot@elliotekj.com