#prometheus API reference

A Prometheus metrics module in two halves. Exposition builds a metric set and renders the Prometheus text format (# HELP / # TYPE / sample lines) - pure text over strings / maps / lists / convert, transport-agnostic (write the string to a *.prom file for the node_exporter textfile collector, POST it to a Pushgateway, or serve it from a /metrics handler). Retrieval is a read client for Prometheus's HTTP query API (query / queryRange) over the http module + json. The exposition half runs on both binaries; the query half needs the default jennifer binary (it uses net through http).

Import with import "prometheus.j" as prometheus;. See the prometheus guide for prose and examples.

#Functions

#prometheus.counter(name as string, help as string)

Build an empty counter metric. Throws on an invalid metric name.

Parameters

• name {string} - the metric name ([a-zA-Z_:][a-zA-Z0-9_:]*)
• help {string} - the HELP text (empty to omit the HELP line)

Returns {Metric} - the new counter metric

Throws

• {Error} - kind "prometheus" when the name is invalid

#prometheus.gauge(name as string, help as string)

Build an empty gauge metric. Throws on an invalid metric name.

Parameters

• name {string} - the metric name ([a-zA-Z_:][a-zA-Z0-9_:]*)
• help {string} - the HELP text (empty to omit the HELP line)

Returns {Metric} - the new gauge metric

Throws

• {Error} - kind "prometheus" when the name is invalid

#prometheus.histogram(name as string, help as string, buckets as list of float)

Build an empty histogram metric. Buckets are the cumulative upper bounds (le); they are sorted ascending, and an +Inf bucket is always rendered in addition to the given bounds. Throws on an invalid metric name.

Parameters

• name {string} - the metric name ([a-zA-Z_:][a-zA-Z0-9_:]*)
• help {string} - the HELP text (empty to omit the HELP line)
• buckets {list of float} - the cumulative upper bounds (le); sorted ascending internally

Returns {Metric} - the new histogram metric

Throws

• {Error} - kind "prometheus" when the name is invalid

#prometheus.observe(metric as Metric, labels as map of string to string, value as float)

Record an observation for a label set, returning a new Metric (value-semantic). For a Counter / Gauge, a sample with an equal label set is replaced (last write wins). For a Histogram / Summary, the observation accumulates: the count and sum grow, histogram buckets increment, and summary observations are retained for quantile computation. Throws on an invalid label name.

Parameters

• metric {Metric} - the metric to extend
• labels {map of string to string} - the sample's label set ({} for none)
• value {float} - the observed value

Returns {Metric} - a new Metric with the observation recorded

Throws

• {Error} - kind "prometheus" when a label name is invalid

#prometheus.observeAt(metric as Metric, labels as map of string to string, value as float, timestampMs as int)

Record an observation carrying an explicit millisecond timestamp, returning a new Metric (value-semantic). Same accumulation rules as observe; the timestamp is appended after the value in the rendered exposition (metric value timestamp). Throws on an invalid label name.

Parameters

• metric {Metric} - the metric to extend
• labels {map of string to string} - the sample's label set ({} for none)
• value {float} - the observed value
• timestampMs {int} - the sample timestamp in milliseconds since the Unix epoch

Returns {Metric} - a new Metric with the timestamped observation recorded

Throws

• {Error} - kind "prometheus" when a label name is invalid

#prometheus.pushgatewayPath(job as string, grouping as map of string to string)

Build the Pushgateway URL path for a job and a set of grouping labels: /metrics/job/<job>/<k1>/<v1>/... with the job name and label values percent-encoded and the grouping keys sorted for a deterministic path. The caller POSTs the render output to base + pushgatewayPath(job, grouping). A pure string helper - no network. Throws on an invalid grouping label name.

Parameters

• job {string} - the Pushgateway job name
• grouping {map of string to string} - additional grouping labels ({} for none)

Returns {string} - the Pushgateway path segment (leading slash, no trailing slash)

Throws

• {Error} - kind "prometheus" when a grouping label name is invalid

#prometheus.query(base as string, promql as string)

Run an instant query against base (a Prometheus server URL) via /api/v1/query, returning the parsed result set.

Parameters

• base {string} - the Prometheus base URL (e.g. "http://localhost:9090")
• promql {string} - the PromQL expression

Returns {Result} - the parsed result set

Throws

• {Error} - kind "prometheus" when the server reports a query error

#prometheus.queryRange(base as string, promql as string, start as string, end as string, step as string)

Run a range query against base via /api/v1/query_range, returning the parsed result matrix. start / end are RFC 3339 or Unix-timestamp strings; step is a duration ("15s") or a seconds string.

Parameters

• base {string} - the Prometheus base URL
• promql {string} - the PromQL expression
• start {string} - the range start (RFC 3339 or Unix timestamp)
• end {string} - the range end (RFC 3339 or Unix timestamp)
• step {string} - the resolution step (duration or seconds)

Returns {Result} - the parsed result matrix

Throws

• {Error} - kind "prometheus" when the server reports a query error

#prometheus.render(metrics as list of Metric)

Render a list of metrics as the Prometheus text exposition format. A Histogram emits _bucket{le="..."} (cumulative, ascending, +Inf last), _sum, and _count series; a Summary emits {quantile="..."}, _sum, and _count series. A sample carrying a timestamp appends it after the value.

Parameters

• metrics {list of Metric} - the metrics to render

Returns {string} - the exposition text (one trailing newline per line)

#prometheus.summary(name as string, help as string, quantiles as list of float)

Build an empty summary metric. Quantiles are values in [0, 1]; they are sorted ascending and reported as {quantile="..."} child series, computed from the observed values at render time. Throws on an invalid metric name or an out-of-range quantile.

Parameters

• name {string} - the metric name ([a-zA-Z_:][a-zA-Z0-9_:]*)
• help {string} - the HELP text (empty to omit the HELP line)
• quantiles {list of float} - the reported quantiles, each in [0, 1]; sorted ascending internally

Returns {Metric} - the new summary metric

Throws

• {Error} - kind "prometheus" when the name is invalid or a quantile is out of range

#Structs

#prometheus.Metric

A metric family: a name, help text, a type, its samples, and (for a Histogram / Summary) its bucket bounds / quantiles.

#prometheus.Point

One (timestamp, value) point of a query result series.

#prometheus.Result

A parsed query result set.

#prometheus.Sample

One recorded series of a metric, keyed by its label set. For a Counter or Gauge only value is used. For a Histogram, count / sum accumulate and buckets holds the cumulative per-bucket counts (parallel to the owning Metric.buckets). For a Summary, count / sum accumulate and observations holds the raw observed values (quantiles are computed at render time). An optional millisecond timestamp is appended after the value when hasTimestamp is set.

#prometheus.Series

One result series: its label set and its points (one point for an instant vector, many for a range matrix).

#Enums

#prometheus.MetricType

A Prometheus metric type: Counter (a monotonically increasing total), Gauge (a value that can go up and down), Histogram (bucketed observations with _bucket / _sum / _count child series), or Summary (quantile observations with {quantile="..."} / _sum / _count series).