instrument_metric (instrument v0.6.1)

Main API facade for metrics instrumentation.

This module provides a unified interface for creating and manipulating metrics including counters, gauges, and histograms. It supports both simple metrics and vector metrics (metrics with labels).

Simple Metrics

  Counter = instrument:new_counter(requests_total, <<"Total HTTP requests">>),
  instrument:inc_counter(Counter),
  instrument:inc_counter(Counter, 5).

Vector Metrics (Labeled)

  instrument:new_counter_vec(http_requests, <<"Requests">>, [method, status]),
  instrument:inc_counter_vec(http_requests, [<<"GET">>, <<"200">>]).

For OpenTelemetry-compatible metrics, see instrument_meter.

Summary

Types

help/0

label/0

label_value/0

labels/0

metric/0

metric_name/0

metric_type/0

Functions

clear_labels(Vector)

dec_gauge(Gauge)

dec_gauge(Gauge, Value)

dec_gauge_vec(Name, LabelValues)

dec_gauge_vec(Name, LabelValues, Value)

get_counter(Counter)

get_counter_vec(Name, LabelValues)

get_gauge(Gauge)

get_gauge_vec(Name, LabelValues)

get_histogram(Hist)

get_histogram_vec(Name, LabelValues)

get_vector_with(Vector, Fun)

inc_counter(Counter)

inc_counter(Counter, Value)

inc_counter_vec(Name, LabelValues)

inc_counter_vec(Name, LabelValues, Value)

inc_gauge(Gauge)

inc_gauge(Gauge, Value)

inc_gauge_vec(Name, LabelValues)

inc_gauge_vec(Name, LabelValues, Value)

labels(Name, LabelValues)

new_counter(Name, Help)

new_counter_vec(Name, Help, Labels)

new_gauge(Name, Help)

new_gauge_vec(Name, Help, Labels)

new_histogram(Name, Help)

new_histogram(Name, Help, Buckets)

new_histogram_vec(Name, Help, Labels)

new_histogram_vec(Name, Help, Labels, Buckets)

new_vector(Labels, MetricType, Name, Help)

new_vector(Labels, MetricType, Name, Help, Buckets)

observe_histogram(Hist, Value)

observe_histogram_vec(Name, LabelValues, Value)

register(Metric)

remove_label(Vector, Label)

set_gauge(Gauge, Value)

set_gauge_to_current_time(Gauge)

set_gauge_vec(Name, LabelValues, Value)

unregister(Name)

unregister_all()

with_label(Vector, Label, Fun)

with_label(Vector, Label, Fun, Val)

Types

help/0

-type help() :: string() | binary().

label/0

-type label() :: string() | atom() | binary().

label_value/0

-type label_value() :: [label()] | #{}.

labels/0

-type labels() :: [label()].

metric/0

-type metric() ::
          #metric{name :: term(),
                  handle :: term(),
                  collect :: tuple(),
                  description :: binary() | undefined,
                  unit :: binary() | undefined,
                  meter :: binary() | undefined,
                  attributes :: map()} |
          atom().

metric_name/0

-type metric_name() :: string() | atom() | binary().

metric_type/0

-type metric_type() :: gauge | counter | histogram.

Functions

clear_labels(Vector)

-spec clear_labels(Vector :: metric()) -> ok.

dec_gauge(Gauge)

-spec dec_gauge(Gauge :: metric()) -> Result :: ok | {error, not_found}.

dec_gauge(Gauge, Value)

-spec dec_gauge(Gauge :: metric(), Value :: number()) -> Result :: ok | {error, not_found}.

dec_gauge_vec(Name, LabelValues)

-spec dec_gauge_vec(Name :: metric_name(), LabelValues :: list()) -> ok | {error, term()}.

dec_gauge_vec(Name, LabelValues, Value)

-spec dec_gauge_vec(Name :: metric_name(), LabelValues :: list(), Value :: number()) ->
                       ok | {error, term()}.

get_counter(Counter)

-spec get_counter(Counter :: metric()) -> Result :: float() | {error, not_found}.

get_counter_vec(Name, LabelValues)

-spec get_counter_vec(Name :: metric_name(), LabelValues :: list()) -> float() | {error, term()}.

get_gauge(Gauge)

-spec get_gauge(Gauge :: metric()) -> Result :: float() | {error, not_found}.

get_gauge_vec(Name, LabelValues)

-spec get_gauge_vec(Name :: metric_name(), LabelValues :: list()) -> float() | {error, term()}.

get_histogram(Hist)

-spec get_histogram(Hist :: metric()) -> Value :: term().

get_histogram_vec(Name, LabelValues)

-spec get_histogram_vec(Name :: metric_name(), LabelValues :: list()) -> map() | {error, term()}.

get_vector_with(Vector, Fun)

-spec get_vector_with(Vector :: metric(), Fun :: mfa()) -> Result :: term().

inc_counter(Counter)

-spec inc_counter(Counter :: metric()) -> Result :: ok | {error, not_found}.

inc_counter(Counter, Value)

-spec inc_counter(Counter :: metric(), Value :: number()) -> Result :: ok | {error, not_found}.

inc_counter_vec(Name, LabelValues)

-spec inc_counter_vec(Name :: metric_name(), LabelValues :: list()) -> ok | {error, term()}.

inc_counter_vec(Name, LabelValues, Value)

-spec inc_counter_vec(Name :: metric_name(), LabelValues :: list(), Value :: number()) ->
                         ok | {error, term()}.

inc_gauge(Gauge)

-spec inc_gauge(Gauge :: metric()) -> Result :: ok | {error, not_found}.

inc_gauge(Gauge, Value)

-spec inc_gauge(Gauge :: metric(), Value :: number()) -> Result :: ok | {error, not_found}.

inc_gauge_vec(Name, LabelValues)

-spec inc_gauge_vec(Name :: metric_name(), LabelValues :: list()) -> ok | {error, term()}.

inc_gauge_vec(Name, LabelValues, Value)

-spec inc_gauge_vec(Name :: metric_name(), LabelValues :: list(), Value :: number()) ->
                       ok | {error, term()}.

labels(Name, LabelValues)

-spec labels(Name :: metric_name(), LabelValues :: list()) -> metric() | {error, term()}.

new_counter(Name, Help)

-spec new_counter(Name :: metric_name(), Help :: help()) -> Counter :: metric().

new_counter_vec(Name, Help, Labels)

-spec new_counter_vec(Name :: metric_name(), Help :: help(), Labels :: labels()) -> ok.

new_gauge(Name, Help)

-spec new_gauge(Name :: metric_name(), Help :: help()) -> Gauge :: metric().

new_gauge_vec(Name, Help, Labels)

-spec new_gauge_vec(Name :: metric_name(), Help :: help(), Labels :: labels()) -> ok.

new_histogram(Name, Help)

-spec new_histogram(Name :: metric_name(), Help :: help()) -> Hist :: metric().

new_histogram(Name, Help, Buckets)

-spec new_histogram(Name :: metric_name(), Help :: help(), Buckets :: list()) -> Hist :: metric().

new_histogram_vec(Name, Help, Labels)

-spec new_histogram_vec(Name :: metric_name(), Help :: help(), Labels :: labels()) -> ok.

new_histogram_vec(Name, Help, Labels, Buckets)

-spec new_histogram_vec(Name :: metric_name(), Help :: help(), Labels :: labels(), Buckets :: list()) ->
                           ok.

new_vector(Labels, MetricType, Name, Help)

-spec new_vector(Labels :: labels(), MetricType :: metric_type(), Name :: metric_name(), Help :: help()) ->
                    Vector :: metric().

new_vector(Labels, MetricType, Name, Help, Buckets)

-spec new_vector(Labels :: labels(),
                 MetricType :: metric_type(),
                 Name :: metric_name(),
                 Help :: help(),
                 Buckets :: list()) ->
                    Vector :: metric().

observe_histogram(Hist, Value)

-spec observe_histogram(Hist :: metric(), Value :: number()) -> ok | {error, not_found}.

observe_histogram_vec(Name, LabelValues, Value)

-spec observe_histogram_vec(Name :: metric_name(), LabelValues :: list(), Value :: number()) ->
                               ok | {error, term()}.

register(Metric)

remove_label(Vector, Label)

-spec remove_label(Vector :: metric(), Label :: label_value()) -> Result :: term().

set_gauge(Gauge, Value)

-spec set_gauge(Gauge :: metric(), Value :: number()) -> Result :: ok | {error, not_found}.

set_gauge_to_current_time(Gauge)

-spec set_gauge_to_current_time(Gauge :: metric()) -> Result :: ok | {error, not_found}.

set_gauge_vec(Name, LabelValues, Value)

-spec set_gauge_vec(Name :: metric_name(), LabelValues :: list(), Value :: number()) ->
                       ok | {error, term()}.

unregister(Name)

unregister_all()

with_label(Vector, Label, Fun)

-spec with_label(Vector :: metric(), Label :: label_value(), Fun :: mfa()) -> Result :: term().

with_label(Vector, Label, Fun, Val)

-spec with_label(Vector :: metric(), Label :: label_value(), Fun :: mfa(), Val :: number()) ->
                    Result :: term().