Peep

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).

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:

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:

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

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/peep.

Tests

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.