Prometheus.ex

v3.0.5

Prometheus.ex v3.0.5 Prometheus.Metric.Histogram View Source

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 macros)

    • :default;
    • {:linear, start, step, count};
    • {:exponential, start, step, count}.

Example:


defmodule ExampleInstrumenter do
  use Prometheus.Metric

  ## to be called at app/supervisor startup.
  ## to tolerate restarts use declare.
  def setup do
    Histogram.new([name: :http_request_duration_milliseconds,
                   labels: [:method],
                   buckets: [100, 300, 500, 750, 1000],
                   help: "Http Request execution time."])
  end

  def instrument(%{time: time, method: method}) do
    Histogram.observe([name: :http_request_duration_milliseconds, labels: [method]],
                      time)
  end
end

Link to this section Summary

Functions

declare(spec)

Creates a histogram using spec. Histogram cannot have a label named "le"

new(spec)

Creates a histogram using spec. Histogram cannot have a label named "le"

observe(spec, amount \\ 1)

Observes the given amount

observe_duration(spec, body)

Observes the amount of time spent executing body

remove(spec)

Removes histogram series identified by spec

reset(spec)

Resets the value of the histogram identified by spec

value(spec)

Returns the value of the histogram identified by spec. If there is no histogram for given labels combination, returns :undefined

Link to this section Functions

Link to this function

declare(spec) View Source

Creates a histogram using spec. Histogram cannot have a label named "le".

If a histogram with the same spec exists returns false.

Raises Prometheus.MissingMetricSpecKeyError if required spec key is missing.
Raises Prometheus.InvalidMetricNameError if metric name is invalid.
Raises Prometheus.InvalidMetricHelpError if help is invalid.
Raises Prometheus.InvalidMetricLabelsError if labels isn't a list.
Raises Prometheus.InvalidMetricNameError if label name is invalid.
Raises Prometheus.InvalidValueError exception if duration_unit is unknown or doesn't match metric name.

Histogram-specific exceptions:

Raises Prometheus.HistogramNoBucketsError if buckets are missing, not a list, empty list or not known buckets spec.
Raises Prometheus.HistogramInvalidBucketsError if buckets aren't in increasing order.
Raises Prometheus.HistogramInvalidBoundError if bucket bound isn't a number.

Link to this function

new(spec) View Source

Creates a histogram using spec. Histogram cannot have a label named "le".

Raises Prometheus.MissingMetricSpecKeyError if required spec key is missing.
Raises Prometheus.InvalidMetricNameError if metric name is invalid.
Raises Prometheus.InvalidMetricHelpError if help is invalid.
Raises Prometheus.InvalidMetricLabelsError if labels isn't a list.
Raises Prometheus.InvalidMetricNameError if label name is invalid.
Raises Prometheus.InvalidValueError exception if duration_unit is unknown or doesn't match metric name.
Raises Prometheus.MFAlreadyExistsError if a histogram with the same spec exists.

Histogram-specific exceptions:

Raises Prometheus.HistogramNoBucketsError if buckets are missing, not a list, empty list or not known buckets spec.
Raises Prometheus.HistogramInvalidBucketsError if buckets aren't in increasing order.
Raises Prometheus.HistogramInvalidBoundError if bucket bound isn't a number.

Link to this function

observe(spec, amount \\ 1) View Source

Observes the given amount.

Raises Prometheus.InvalidValueError exception if amount isn't a number.
Raises Prometheus.UnknownMetricError exception if a histogram for spec can't be found.
Raises Prometheus.InvalidMetricArityError exception if labels count mismatch.

Link to this macro

observe_duration(spec, body) View Source (macro)

Observes the amount of time spent executing body.

Raises Prometheus.UnknownMetricError exception if a histogram for spec can't be found.
Raises Prometheus.InvalidMetricArityError exception if labels count mismatch. Raises Prometheus.InvalidValueError exception if fun isn't a function or block.

Link to this function

remove(spec) View Source

Removes histogram series identified by spec.

Raises Prometheus.UnknownMetricError exception if a histogram for spec can't be found.
Raises Prometheus.InvalidMetricArityError exception if labels count mismatch.

Link to this function

reset(spec) View Source

Resets the value of the histogram identified by spec.

Raises Prometheus.UnknownMetricError exception if a histogram for spec can't be found.
Raises Prometheus.InvalidMetricArityError exception if labels count mismatch.

Link to this function

value(spec) View Source

Returns the value of the histogram identified by spec. If there is no histogram for given labels combination, returns :undefined.

Raises Prometheus.UnknownMetricError exception if a histogram for spec can't be found.
Raises Prometheus.InvalidMetricArityError exception if labels count mismatch.