prometheus.Histogram.create()
Creates a new histogram metric with the specified name, description, buckets, and labels.
Syntax
In this syntax diagram, the square brackets ([ ]) are part of the syntax.
prometheus.Histogram.create(
name STRING,
description STRING,
[ buckets ],
[ labels ] )
RETURNS prometheus.Histogram
- name is the name of the histogram (no spaces allowed).
- description is a description of the purpose of the histogram.
- buckets is a comma-separated list of values of type FLOAT between square brackets that define the bucket boundaries.
- labels is a comma-separated list of label names inside square
brackets that define the metric's dimensions. A label name cannot be empty. For example, a metric
created with
["method","endpoint"]has two dimensions. Where the metric needs no dimensions, use empty brackets[].
Usage
Use the prometheus.Histogram.create() method to create a new histogram
metric to observe and record the distribution of numerical values over time in configurable ranges,
known as "buckets", that categorize the observed values.
Histograms are particularly useful for measuring performance-related data, such as response times or request sizes. This information is useful for calculating averages and other statistical measures, which provide insights into the performance characteristics of a system, such as how quickly requests are processed.
The labels parameter defines the dimensions for the metric, and buckets defines a distribution of values ranges to observe over time.
The bucket boundaries are set when the metric is created and cannot be changed afterwards, so choose them before you deploy.
Choose label names whose values come from a small set you can name in advance, such as a category, a status, or an outcome. Avoid a label name whose values are unbounded, such as an order number or a user name. Each combination of label values creates its own series, so such a label produces one series per order or per user, which cannot be aggregated into anything useful. The metric also grows until it exhausts the Prometheus server.
Example
-- Define the histogram variable
DEFINE histogram prometheus.Histogram
-- Create a histogram metric with three buckets and two labels
LET histogram = prometheus.Histogram.create("histogram_request_duration",
"request duration in seconds", [0.25,0.5,1],
["url", "status"])