Skip to content

Latest commit

 

History

History
331 lines (206 loc) · 11.5 KB

prometheus_histogram.md

File metadata and controls

331 lines (206 loc) · 11.5 KB
Raw

Module prometheus_histogram

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

Behaviours: prometheus_collector, prometheus_metric.

Description

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;
  • :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/1Equivalent to buckets(default, Name, []).
buckets/2Equivalent to buckets(default, Name, LabelValues).
buckets/3Returns buckets of the histogram identified by Registry, Name and LabelValues.
declare/1Creates a histogram using Spec.
deregister/1Equivalent to deregister(default, Name).
deregister/2 Removes all histogram series with name Name and removes Metric Family from Registry.
new/1Creates a histogram using Spec.
observe/2Equivalent to observe(default, Name, [], Value).
observe/3Equivalent to observe(default, Name, LabelValues, Value).
observe/4Observes the given Value.
observe_duration/2Equivalent to observe_duration(default, Name, [], Fun).
observe_duration/3Equivalent to observe_duration(default, Name, LabelValues, Fun).
observe_duration/4Tracks the amount of time spent executing Fun.
remove/1Equivalent to remove(default, Name, []).
remove/2Equivalent to remove(default, Name, LabelValues).
remove/3Removes histogram series identified by Registry, Name and LabelValues.
reset/1Equivalent to reset(default, Name, []).
reset/2Equivalent to reset(default, Name, LabelValues).
reset/3Resets the value of the histogram identified by Registry, Name and LabelValues.
value/1Equivalent to value(default, Name, []).
value/2Equivalent to value(default, Name, LabelValues).
value/3Returns the value of the histogram identified by Registry, Name and LabelValues.
values/2

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 {no_buckets, Buckets} error if Buckets are missing, not a list, empty list or not known buckets spec.
Raises {invalid_buckets, Buckets, Message} error if Buckets aren't in increasing order.
Raises {invalid_bound, Bound} error if Bound isn't a number.

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, _}.

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.

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

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.

value/1

value(Name) -> any()

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

value/2

value(Name, LabelValues) -> any()

Equivalent to value(default, Name, LabelValues).

value/3

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

Returns the value of the histogram identified by Registry, Name and LabelValues. If there is no histogram for LabelValues, returns undefined.

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.

values/2

values(Registry, Name) -> any()