# `Prometheus.Metric.Histogram`
[🔗](https://github.com/prometheus-erl/prometheus.ex/blob/v5.1.0/lib/prometheus/metric/histogram.ex#L1)

A Histogram tracks the size and number of events in buckets.
You can use Histograms for aggregating 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

```

# `declare`

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.<br>
Raises `Prometheus.InvalidMetricNameError` if metric name is invalid.<br>
Raises `Prometheus.InvalidMetricHelpError` if help is invalid.<br>
Raises `Prometheus.InvalidMetricLabelsError` if labels isn't a list.<br>
Raises `Prometheus.InvalidMetricNameError` if label name is invalid.<br>
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.<br>
Raises `Prometheus.HistogramInvalidBucketsError` if buckets aren't
in increasing order.<br>
Raises `Prometheus.HistogramInvalidBoundError` if bucket bound isn't a number.

# `new`

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

Raises `Prometheus.MissingMetricSpecKeyError` if required `spec` key is missing.<br>
Raises `Prometheus.InvalidMetricNameError` if metric name is invalid.<br>
Raises `Prometheus.InvalidMetricHelpError` if help is invalid.<br>
Raises `Prometheus.InvalidMetricLabelsError` if labels isn't a list.<br>
Raises `Prometheus.InvalidMetricNameError` if label name is invalid.<br>
Raises `Prometheus.InvalidValueError` exception if duration_unit is unknown or
doesn't match metric name.<br>
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.<br>
Raises `Prometheus.HistogramInvalidBucketsError` if buckets aren't
in increasing order.<br>
Raises `Prometheus.HistogramInvalidBoundError` if bucket bound isn't a number.

# `observe`

Observes the given amount.

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

# `observe_duration`
*macro* 

Observes the amount of time spent executing `body`.

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

# `remove`

Removes histogram series identified by spec.

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

# `reset`

Resets the value of the histogram identified by `spec`.

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

# `value`

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.<br>
Raises `Prometheus.InvalidMetricArityError` exception if labels count mismatch.

---

*Consult [api-reference.md](api-reference.md) for complete listing*