Module prometheus_histogram

Description
Function Index
Function Details

A Histogram tracks the size and number of events in buckets.

Behaviours: prometheus_collector, prometheus_metric.

Description

A Histogram tracks the size and number of events in buckets. You can use Histograms for aggregatable calculation of quantiles.

Example use cases for Histograms:

Response latency
Request size

Histogram expects buckets` key in a metric spec. Buckets can be: - a list of numbers in increasing order; one of the generate specs (shortcuts for `prometheus_buckets functions) - :default; - {:linear, start, step, count}; - {:exponential, start, step, count}

Example:

  -module(example_instrumenter).
  setup() ->
    prometheus_histogram:declare([{name, http_request_duration_milliseconds},
                                  {labels, [method]},
                                  {buckets, [100, 300, 500, 750, 1000]},
                                  {help, "Http Request execution time."}]).
 
  instrument(Time, Method) ->
    %% Time must be in native units, otherwise duration_unit must be false
    prometheus_histogram:observe(http_request_duration_milliseconds,
                                 [Method], Time).

Function Index

buckets/1	Equivalent to `buckets(default, Name, [])`.
buckets/2	Equivalent to `buckets(default, Name, LabelValues)`.
buckets/3	Returns buckets of the histogram identified by `Registry`, `Name` and `LabelValues`.
declare/1	Creates a histogram using `Spec`.
declare/2	(Deprecated.)
deregister/1	Equivalent to `deregister(default, Name)`.
deregister/2	Removes all histogram series with name `Name` and removes Metric Family from `Registry`.
dobserve/2	Equivalent to `dobserve(default, Name, [], Value)`.
dobserve/3	Equivalent to `dobserve(default, Name, LabelValues, [], Value)`.
dobserve/4	Observes the given `Value`.
new/1	Creates a histogram using `Spec`.
new/2	(Deprecated.)
observe/2	Equivalent to `observe(default, Name, [], Value)`.
observe/3	Equivalent to `observe(default, Name, LabelValues, Value)`.
observe/4	Observes the given `Value`.
observe_duration/2	Equivalent to `observe_duration(default, Name, [], Fun)`.
observe_duration/3	Equivalent to `observe_duration(default, Name, LabelValues, Fun)`.
observe_duration/4	Tracks the amount of time spent executing `Fun`.
remove/1	Equivalent to `remove(default, Name, [])`.
remove/2	Equivalent to `remove(default, Name, LabelValues)`.
remove/3	Removes histogram series identified by `Registry`, `Name` and `LabelValues`.
reset/1	Equivalent to `reset(default, Name, [])`.
reset/2	Equivalent to `reset(default, Name, LabelValues)`.
reset/3	Resets the value of the histogram identified by `Registry`, `Name` and `LabelValues`.
value/1	Equivalent to `value(default, Name, [])`.
value/2	Equivalent to `value(default, Name, LabelValues)`.
value/3	Returns the value of the histogram identified by `Registry`, `Name` and `LabelValues`.

Function Details

buckets/1

buckets(Name) -> any()

Equivalent to buckets(default, Name, []).

buckets/2

buckets(Name, LabelValues) -> any()

Equivalent to buckets(default, Name, LabelValues).

buckets/3

buckets(Registry, Name, LabelValues) -> any()

Returns buckets of the histogram identified by Registry, Name and LabelValues.

declare/1

declare(Spec) -> any()

Creates a histogram using Spec. If a histogram with the same Spec exists returns false.

Raises {missing_metric_spec_key, Key, Spec} error if required Soec key is missing.
Raises {invalid_metric_name, Name, Message} error if metric Name is invalid.
Raises {invalid_metric_help, Help, Message} error if metric Help is invalid.
Raises {invalid_metric_labels, Labels, Message} error if Labels isn't a list.
Raises {invalid_label_name, Name, Message} error if Name isn't a valid label name.
Raises {invalid_value_error, Value, MessagE} error if duration_unit is unknown or doesn't match metric name.

Histogram-specific errors:
Raises {histogram_no_buckets, Buckets} error if Buckets are missing, not a list, empty list or not known buckets spec.
Raises {histogram_invalid_buckets, Buckets, Message} error if Buckets aren't in increasing order.
Raises {histogram_invalid_bound, Bound} error if Bound isn't a number.

declare/2

declare(Spec, Registry) -> any()

This function is deprecated: Please use declare/1 with registry key instead.

deregister/1

deregister(Name) -> any()

Equivalent to deregister(default, Name).

deregister/2

deregister(Registry, Name) -> any()

Removes all histogram series with name Name and removes Metric Family from Registry.

After this call new/1 for Name and Registry will succeed.

Returns {true, _} if Name was a registered histogram. Otherwise returns {false, _}.

dobserve/2

dobserve(Name, Value) -> any()

Equivalent to dobserve(default, Name, [], Value).

dobserve/3

dobserve(Name, LabelValues, Value) -> any()

Equivalent to dobserve(default, Name, LabelValues, [], Value).

dobserve/4

dobserve(Registry, Name, LabelValues, Value) -> any()

Observes the given Value. If Value happened to be a float number even one time(!) you shouldn't use observe/4 after dobserve.

Raises {invalid_value, Value, Message} if Value isn't a number.
Raises {unknown_metric, Registry, Name} error if histogram with named Name can't be found in Registry.
Raises {invalid_metric_arity, Present, Expected} error if labels count mismatch.

new/1

new(Spec) -> any()

Creates a histogram using Spec.

Raises {missing_metric_spec_key, Key, Spec} error if required Soec key is missing.
Raises {invalid_metric_name, Name, Message} error if metric Name is invalid.
Raises {invalid_metric_help, Help, Message} error if metric Help is invalid.
Raises {invalid_metric_labels, Labels, Message} error if Labels isn't a list.
Raises {invalid_label_name, Name, Message} error if Name isn't a valid label name.
Raises {invalid_value_error, Value, Message} error if duration_unit is unknown or doesn't match metric name.
Raises {mf_already_exists, {Registry, Name}, Message} error if a histogram with the same Spec already exists.

new/2

new(Spec, Registry) -> any()

This function is deprecated: Please use new/1 with registry key instead.

observe/2

observe(Name, Value) -> any()

Equivalent to observe(default, Name, [], Value).

observe/3

observe(Name, LabelValues, Value) -> any()

Equivalent to observe(default, Name, LabelValues, Value).

observe/4

observe(Registry, Name, LabelValues, Value) -> any()

Observes the given Value.

Raises {invalid_value, Value, Message} if Value isn't an integer.
Raises {unknown_metric, Registry, Name} error if histogram with named Name can't be found in Registry.
Raises {invalid_metric_arity, Present, Expected} error if labels count mismatch.

observe_duration/2

observe_duration(Name, Fun) -> any()

Equivalent to observe_duration(default, Name, [], Fun).

observe_duration/3

observe_duration(Name, LabelValues, Fun) -> any()

Equivalent to observe_duration(default, Name, LabelValues, Fun).

observe_duration/4

observe_duration(Registry, Name, LabelValues, Fun) -> any()

Tracks the amount of time spent executing Fun.

Raises {unknown_metric, Registry, Name} error if histogram with named Name can't be found in Registry.
Raises {invalid_metric_arity, Present, Expected} error if labels count mismatch. Raises {invalid_value, Value, Message} if Fun isn't a function.

remove/1

remove(Name) -> any()

Equivalent to remove(default, Name, []).

remove/2

remove(Name, LabelValues) -> any()

Equivalent to remove(default, Name, LabelValues).

remove/3

remove(Registry, Name, LabelValues) -> any()

Removes histogram series identified by Registry, Name and LabelValues.

Raises {unknown_metric, Registry, Name} error if histogram with name Name can't be found in Registry.
Raises {invalid_metric_arity, Present, Expected} error if labels count mismatch.

reset/1

reset(Name) -> any()

Equivalent to reset(default, Name, []).

reset/2

reset(Name, LabelValues) -> any()

Equivalent to reset(default, Name, LabelValues).

reset/3

reset(Registry, Name, LabelValues) -> any()

Resets the value of the histogram identified by Registry, Name and LabelValues.

Raises {unknown_metric, Registry, Name} error if histogram with name Name can't be found in Registry.
Raises {invalid_metric_arity, Present, Expected} error if labels count mismatch.

If duration unit set, sum will be converted to the duration unit. Read more here.

Raises {unknown_metric, Registry, Name} error if histogram named Name can't be found in Registry.
Raises {invalid_metric_arity, Present, Expected} error if labels count mismatch.

Generated by EDoc