Miscellaneous functions

This page covers PromQL functions that do not fit a larger category: absence detection, scalar/vector conversion, histogram quantiles, and the Kloudfuse apdex extension.

absent

Returns a single series with value 1 when the given selector matches nothing, and returns nothing when series exist. This inversion powers absence alerting: a target that stopped reporting produces no series for a normal rule to fire on.

Syntax

absent(<vector expression>)
none

Parameters

Parameter Required Description

<vector expression>

Required

The selector expected to match series.

Example

Check for a metric that does not exist on this cluster — absent returns 1, the signal an alert would fire on.

absent(nonexistent_demo_metric{app_kubernetes_io_instance="kfuse"})
Expected output
app_kubernetes_io_instance Value

kfuse

1

Equality matchers from the selector are carried into the result labels, so the alert knows what went missing.

For absence over a window rather than one instant, use absent_over_time.

apdex

Kloudfuse extension. Computes the Apdex score — (satisfied + tolerated/2) / total — from histogram bucket series, using the two thresholds to classify requests as satisfied (≤ first threshold) or tolerated (≤ second threshold). The score ranges from 0 (all frustrated) to 1 (all satisfied).

Syntax

apdex(<satisfied>, <tolerated>, sum by (le) (rate(<metric>_bucket[<range>])))
none

Parameters

Parameter Required Description

<satisfied>

Required

Threshold at or below which a request counts as satisfied.

<tolerated>

Required

Threshold at or below which a request counts as tolerated.

<metric>_bucket

Required

Histogram bucket series carrying the le label.

Example

Score the Kloudfuse ingester’s Kafka batch sizes with satisfied ≤ 10 and tolerated ≤ 40.

apdex(10, 40,
  sum by (le) (rate(ingester_kafka_batch_length_bucket[5m]))
)
Expected output
Value

0.8824

Thresholds must align with actual bucket boundaries for exact classification; between boundaries the count is interpolated.

apdex is a Kloudfuse extension and is not available in upstream Prometheus.

histogram_quantile

Estimates the given quantile (0 to 1) from the _bucket series of a Prometheus histogram. The canonical form wraps the buckets in sum by (le) (rate(…​)) so the estimate reflects recent behavior and the mandatory le label survives the aggregation.

Syntax

histogram_quantile(<q>, sum by (le) (rate(<metric>_bucket[<range>])))
none

Parameters

Parameter Required Description

<q>

Required

The quantile, between 0 and 1.

<metric>_bucket

Required

Histogram bucket series carrying the le label.

Example

Estimate the 95th-percentile Kafka batch length seen by the Kloudfuse ingester over the last five minutes.

histogram_quantile(0.95,
  sum by (le) (rate(ingester_kafka_batch_length_bucket[5m]))
)
Expected output
Value

37.09

The result is interpolated within a bucket, so precision depends on bucket boundaries.

Any aggregation around the buckets must keep the le label.

scalar

Converts a vector containing exactly one series into a scalar, so its value can be used where PromQL requires a scalar argument. If the input has zero or multiple series, the result is NaN.

Syntax

scalar(<single-series vector>)
none

Parameters

Parameter Required Description

<vector>

Required

An expression that yields exactly one series.

Example

Turn the total Kloudfuse goroutine count into a scalar and re-wrap it as a vector for display.

vector(scalar(sum(go_goroutines{app_kubernetes_io_instance="kfuse"})))
Expected output
Value

386,610

Prefer vector-to-vector arithmetic with on () group_left over scalar() when labels must be preserved.

vector

Returns the given scalar as a vector with one series and no labels. Its main use is the fallback idiom <query> or vector(0), which turns an empty result into an explicit zero so dashboards and downstream arithmetic stay well-defined.

Syntax

vector(<scalar>)
none

Parameters

Parameter Required Description

<scalar>

Required

The value to return.

Example

Count series of a metric that does not exist; the count is empty, so or vector(0) supplies the zero.

count(nonexistent_demo_metric) or vector(0)
Expected output
Value

0

The fallback series has no labels; add them with label_replace if later stages match on labels.