Class Poco::Prometheus::Histogram

File Information

Library: Prometheus
Package: Core
Header: Poco/Prometheus/Histogram.h

Description

A histogram with a configurable number of buckets.

To create a Histogram with labels and three buckets, and register it with the default Registry:

Histogram sampleHistogram("sample_histogram"s, {
    .help = "A sample histogram"s,
    .labelNames = {"label1"s, "label2"s},
    .buckets = {0.5, 1.0, 5.0}
});

To observe a value with a Histogram (with labels):

sampleHistogram.labels({"value1"s, "value2"}).observe(1.5);

To create a Histogram without labels and register it with the default Registry:

Histogram simpleHistogram("simple_histogram"s, {
    .help = "A simple histogram"s,
    .buckets = {0.5, 1.0, 5.0}
});

To observe a value with a Histogram (without labels):

simpleHistogram.observe(1.5);

Inheritance

Direct Base Classes: LabeledMetricImpl < HistogramSample >

All Base Classes: LabeledMetricImpl < HistogramSample >

Member Summary

Member Functions: buckets, createSample, data, exportTo, help, labelNames, observe

Nested Classes

struct Params

Constructors

Histogram

explicit Histogram(
const std::string & name
);

Creates a Histogram with the given name and registers it with the default registry.

Histogram

Histogram(
const std::string & name,
const Params & params
);

Creates a Histogram with the given name and params, and registers it with the default registry.

Histogram

Histogram(
const std::string & name,
Registry * pRegistry
);

Creates a Histogram with the given name and registers it with the given registry (if not nullptr).

Histogram

Histogram(
    const std::string & name,
    const Params & params,
    Registry * pRegistry
);

Creates a Histogram with the given name and params, and registers it with the given registry (if not nullptr).

Destructor

~Histogram

~Histogram() = default;

Destroys the Histogram.

Member Functions

buckets

Histogram & buckets(
const std::vector < double > & bucketBounds
);

Sets the Histogram's bucket upper bounds.

Upper bounds must be strictly ordered from lowest to highest value. The final infinite bucket must not be included.

Must only be set once, immediately after creating the Histogram.

buckets

const std::vector < double > buckets() const;

Returns the configured bucket upper bounds.

createSample

std::unique_ptr < HistogramSample > createSample() const override;

data

HistogramData data() const;

Returns the histogram's data.

exportTo

void exportTo(
Exporter & exporter
) const override;

help

Histogram & help(
const std::string & text
);

Sets the Histogram's help text.

Must only be set once, immediately after creating the Histogram.

labelNames

Histogram & labelNames(
const std::vector < std::string > & labelNames
);

Sets the Histogram's label names.

Must only be set once, immediately after creating the Gauge. The label name "le" must not be used as it is reserved for the histogram.

observe

void observe(
double value
);

Observes the given amount, by increasing the count in the respective bucket.

observe

void observe(
Poco::Clock::ClockVal v
);

Converts the given Clock time in microseconds to seconds and increases the count in the respective bucket.

Can only be used if no labels have been defined.