peep

# Peep

[![Hex version badge](https://img.shields.io/hexpm/v/peep)](https://hex.pm/packages/peep)
[![Hexdocs badge](https://img.shields.io/static/v1?message=hexdocs&label=&color=B1A5EE)](https://hexdocs.pm/peep)
[![Elixir CI badge](https://github.com/rkallos/peep/actions/workflows/elixir.yml/badge.svg)](https://github.com/rkallos/peep/actions/workflows/elixir.yml)
[![Hex licence badge](https://img.shields.io/hexpm/l/peep)](./LICENSE)

`Telemetry.Metrics` reporter for Prometheus and StatsD (including Datadog).

Peep has some important differences from libraries like
`TelemetryMetricsPrometheus.Core` and `TelemetryMetricsStatsd`:

- Instead of sampling or on-demand aggregation of samples, Peep estimates
  distributions using histograms.
- Instead of sending one datagram per telemetry event, Peep's StatsD reporting
  runs periodically, batching all lines into the smallest number of datagram
  packets possible while still obeying the configured `:mtu` setting.

To use it, start a reporter with `start_link/1`, providing a keyword list of
options (see `Peep.Options` for the schema against which options are validated).

```elixir
import Telemetry.Metrics

Peep.start_link(
  name: MyPeep,
  metrics: [
    counter("http.request.count"),
    sum("http.request.payload_size"),
    last_value("vm.memory.total")
  ]
)
```

or put it under a supervisor:

```elixir
import Telemetry.Metrics

children = [
  {Peep, [
    name: MyPeep,
    metrics: [
      counter("http.request.count"),
      sum("http.request.payload_size"),
      last_value("vm.memory.total")
    ]
  ]}
]

Supervisor.start_link(children, ...)
```

By default, Peep does not emit StatsD data. It can be enabled by passing in
configuration with the `statsd` keyword. Peep's StatsD reporting supports Unix
Domain Sockets.

## What's Missing

Currently, there's no implementation of 'summary' metrics. Since histograms are
relatively inexpensive in Peep, we suggest you use 'distribution' metrics
instead.

## Installation

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

```elixir
def deps do
  [
    {:peep, "~> 4.0"}
  ]
end
```

Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
be found at <https://hexdocs.pm/peep>.

## Tests

```sh
mix test
```

`test/shared/storage_test.exs` is a suite that any `Peep.Storage`
implementation can run; its module doc shows how.

### Guidelines

- **A `check` per suite**: each suite has a `check` helper that runs the code
  under test once. It takes the inputs first, then the expectations prefixed
  with `exp_`, e.g. `exp_scrape:` or `exp_export:`.
- **Assert whole values**: outputs are compared whole with `==`, so that an
  unexpected metric, series or line fails the test. Most tests compare a
  scrape, the map returned by `Peep.get_all_metrics/1`.
- **Test a module directly**: the exporters are tested on scrapes, without
  starting a reporter. `PeepTest` covers the path from a `:telemetry` event to
  the scrape.
- **Async suites**: every suite is `async: true`. Tests that emit `:telemetry`
  events use event names unique to the test, so that no other reporter
  receives them.
- **Silent tests**: a passing run prints nothing. A test whose code is
  expected to log is tagged `@tag capture_log: true`, and checks what the code
  did rather than what it logged.
- **Tests must be able to fail**: check that a new test fails without the
  change it covers.