Hercules v0.1.0 Hercules.Histogram View Source

Module for creating histograms and observing events.

To create a histogram, add this to your metrics setup code:

buckets = [100, 250, 500]
Histogram.create!(name: :request_duration_milliseconds, buckets: buckets)

You can specify an optional list of arguments:

  • labels which is a list of atoms
  • help which is string

For example:

Histogram.new!(
  name: :request_duration_milliseconds,
  buckets: buckets,
  labels: [:method],
  help: "Request durations"
)

To record an event, you have to use observe/3 and pass either an integer or a float:

Histogram.observe(:request_duration_milliseconds, 250)

The value time format is inferred from the metric name. If the metric name contains milliseconds, the value will be treated as 250ms. When the value is in seconds or microseconds, you have to convert it manually before passing it to observe/3 or use the optional :unit argument.

When the name does not conform to the convention, you can pass an optional :unit argument to specify the time format, e.g.

Histogram.observe(:request_duration_histogram, 250, unit: :millisecond)

When you create a metric with labels, you will need to also set the labels when calling observe/3, otherwise you will get an exception:

Histogram.observe(:request_duration_milliseconds, 250, labels: ["POST"])

The order of labels values in the list have to match the one when you created the metric.

Link to this section Summary

Functions

Creates a new Histogram metric using given params.

Records a Histogram event.

Link to this section Types

Link to this type

t()

View Source
t() :: %Hercules.Histogram{
  buckets: [float() | integer()],
  help: String.t(),
  labels: [atom()],
  name: atom(),
  registry: atom()
}

Link to this section Functions

Link to this function

new!(params)

View Source
new!([atom()]) :: :ok

Creates a new Histogram metric using given params.

buckets = [100, 250, 500]
Histogram.new!(name: :request_duration_milliseconds, buckets: buckets)

Optional parameters:

  • registry atom, defaults to :default
  • labels list of atoms, defaults to []
  • help string, defaults to ""
Link to this function

observe!(name, value, opts \\ [])

View Source

Records a Histogram event.

The name argument should match the name of a previously registered metric using Histogram.new!/1.

The value is expected to be a numerical value (float or integer).