Prometheus.ex v1.0.0 Prometheus.Metric.Summary

Summary metric, to track the size of events.

Example use cases for Summaries:

  • Response latency;
  • Request size;
  • Response size.

Example:

defmodule MyProxyInstrumenter do

  use Prometheus.Metric

  ## to be called at app/supervisor startup.
  ## to tolerate restarts use declare.
  def setup() do
    Summary.declare([name: :request_size_bytes,
                     help: "Request size in bytes."])

    Summary.declare([name: :response_size_bytes,
                     help: "Response size in bytes."])
  end

  def observe_request(size) do
    Summary.observe([name: :request_size_bytes], size)
  end

  def observe_response(size) do
    Summary.observe([name: :response_size_bytes], size)
  end
end

Summary

Macros

Creates a summary using spec. Summary cannot have a label named “quantile”

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

Creates a summary using spec. Summary cannot have a label named “quantile”

Observes the given amount

Observes the amount of seconds spent executing fun

Removes summary series identified by spec

Resets the value of the summary identified by spec

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

Macros

declare(spec)

Creates a summary using spec. Summary cannot have a label named “quantile”.

If a summary 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.

dobserve(spec, amount \\ 1)

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

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

new(spec)

Creates a summary using spec. Summary cannot have a label named “quantile”.

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 summary with the same spec already exists.

observe(spec, amount \\ 1)

Observes the given amount.

Raises Prometheus.InvalidValueError exception if amount isn’t an integer.
Raises Prometheus.UnknownMetricError exception if a summary for spec can’t be found.
Raises Prometheus.InvalidMetricArityError exception if labels count mismatch.

observe_duration(spec, fun)

Observes the amount of seconds spent executing fun.

Raises Prometheus.UnknownMetricError exception if a summary 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.

remove(spec)

Removes summary series identified by spec.

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

reset(spec)

Resets the value of the summary identified by spec.

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

value(spec)

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

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

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