instrument

Fast metrics library for Erlang with Prometheus export. Uses NIFs for high-performance atomic counters, gauges, and histograms.

Features

• High-performance counters, gauges, and histograms using NIFs
• Vec API for labeled metrics (prometheus-cpp style)
• Built-in Prometheus text format export
• Simple, minimal API

Installation

rebar3

{deps, [
    {instrument, "0.2.0"}
]}.

mix

{:instrument, "~> 0.2.0"}

Quick Start

Counters

%% Create a counter
Counter = instrument:new_counter(http_requests_total, "Total HTTP requests"),

%% Increment
instrument:inc_counter(Counter),
instrument:inc_counter(Counter, 5),

%% Get value
Value = instrument:get_counter(Counter).

Gauges

%% Create a gauge
Gauge = instrument:new_gauge(temperature, "Current temperature"),

%% Set, increment, decrement
instrument:set_gauge(Gauge, 23.5),
instrument:inc_gauge(Gauge),
instrument:dec_gauge(Gauge, 2),

%% Get value
Value = instrument:get_gauge(Gauge).

Histograms

%% Create with default buckets
Histogram = instrument:new_histogram(request_duration_seconds, "Request duration"),

%% Create with custom buckets
Histogram2 = instrument:new_histogram(response_size_bytes, "Response size",
    [100, 500, 1000, 5000, 10000]),

%% Observe values
instrument:observe_histogram(Histogram, 0.25),

%% Get histogram data
#{count := Count, sum := Sum, buckets := Buckets} = instrument:get_histogram(Histogram).

Vec API (Labeled Metrics)

The Vec API provides labeled metrics similar to prometheus-cpp:

%% Create a counter vec with labels
instrument:new_counter_vec(http_requests_total, "HTTP requests", [method, path]),

%% Increment with label values
instrument:inc_counter_vec(http_requests_total, ["GET", "/api/users"]),
instrument:inc_counter_vec(http_requests_total, ["POST", "/api/users"], 1),

%% Get a specific labeled metric
Counter = instrument:labels(http_requests_total, ["GET", "/api/users"]),
instrument:inc_counter(Counter),

%% Gauge vec
instrument:new_gauge_vec(connections, "Active connections", [pool]),
instrument:set_gauge_vec(connections, ["db"], 5),

%% Histogram vec
instrument:new_histogram_vec(request_duration, "Request duration", [endpoint]),
instrument:observe_histogram_vec(request_duration, ["/api"], 0.125).

Prometheus Export

Export metrics in Prometheus text format:

%% Get formatted metrics
Output = instrument_prometheus:format(),

%% Get content type for HTTP response
ContentType = instrument_prometheus:content_type().
%% Returns: <<"text/plain; version=0.0.4; charset=utf-8">>

Example output:

# HELP http_requests_total Total HTTP requests
# TYPE http_requests_total counter
http_requests_total{method="GET",path="/api"} 150
http_requests_total{method="POST",path="/api"} 42

Building

rebar3 compile

Running Tests

rebar3 ct

License

MIT License - see LICENSE for details.