Search documentation of macula

# macula_metrics (macula v4.4.1)

View Source

Node-wide Prometheus-style metric registry for macula-net.

Phase 4.1 — see PLAN_MACULA_NET_PHASE4_1_OBSERVABILITY.md.

Backed by ETS:

- `?META` — `{Name, Type, Labels, Help, Buckets}`
- `?VALS` — `{{counter, Name, LabelVals}, Count}`
  `{{gauge, Name, LabelVals}, Value}`
  `{{hist_bk, Name, LabelVals, I}, Count}` (per bucket)
  `{{hist_sm, Name, LabelVals}, SumMicros}`
  `{{hist_ct, Name, LabelVals}, Count}`

Counters and histograms use `ets:update_counter/4` which is lock-free per-key; no gen_server roundtrip on the hot path.

Telemetry handlers are attached at start. Hot paths emit via `telemetry:execute/3`; the handler maps event_name + measurements to counter/histogram updates. Grep for `telemetry:execute` to find every measurement point.

Gauges are polled (1s) from source-of-truth (ETS sizes).

# Summary

## Types

label_name/0
label_val/0
label_vals/0
metric_name/0

## Functions

gather()

Returns the full metric snapshot in a render-friendly shape.

handle_call(Msg, From, State)
handle_cast(Msg, State)
handle_info(_, State)
handle_telemetry_event(Other, M, Md, Cfg)
inc_counter(Name, LabelVals, N)
init(Opts)
observe(Name, LabelVals, V)
register_counter(Name, Labels, Help)
register_gauge(Name, Labels, Help)
register_histogram(Name, Labels, Help, Buckets)
reset_all()

Wipe every counter / gauge / histogram value. Metadata stays.

set_gauge(Name, LabelVals, V)
start_link()
start_link(Opts)
stop()
terminate(_, State)

# Types

# label_name/0

    -type label_name() :: atom().

# label_val/0

    -type label_val() :: binary() | atom().

# label_vals/0

    -type label_vals() :: [{label_name(), label_val()}].

# metric_name/0

    -type metric_name() :: binary().

# Functions

# gather()

    -spec gather() -> [map()].

Returns the full metric snapshot in a render-friendly shape.

# handle_call(Msg, From, State)

# handle_cast(Msg, State)

# handle_info(_, State)

# handle_telemetry_event(Other, M, Md, Cfg)

# inc_counter(Name, LabelVals, N)

    -spec inc_counter(metric_name(), label_vals(), pos_integer()) -> ok.

# init(Opts)

# observe(Name, LabelVals, V)

    -spec observe(metric_name(), label_vals(), number()) -> ok.

# register_counter(Name, Labels, Help)

    -spec register_counter(metric_name(), [label_name()], binary()) -> ok.

# register_gauge(Name, Labels, Help)

    -spec register_gauge(metric_name(), [label_name()], binary()) -> ok.

# register_histogram(Name, Labels, Help, Buckets)

    -spec register_histogram(metric_name(), [label_name()], binary(), [number()]) -> ok.

# reset_all()

    -spec reset_all() -> ok.

Wipe every counter / gauge / histogram value. Metadata stays.

# set_gauge(Name, LabelVals, V)

    -spec set_gauge(metric_name(), label_vals(), number()) -> ok.

# start_link()

    -spec start_link() -> {ok, pid()} | {error, term()}.

# start_link(Opts)

    -spec start_link(map()) -> {ok, pid()} | {error, term()}.

# stop()

    -spec stop() -> ok.

# terminate(_, State)