@zuke/prometheus

A target Prometheus is scraping.

An alert, active or pending, as the rules and alerts endpoints report it.

An alerting rule.

The active alerts.

Prometheus, or an HTTP layer in front of it, refused the call: a non-2xx status, or an envelope whose status is "error".

try {
  await PrometheusTasks.query((s) => s.url(url).query("rate(x[5m]"));
} catch (error) {
  if (error instanceof PrometheusApiError && error.errorType === "bad_data") {
    // the expression did not parse
  }
}

An explicit access key (set by PrometheusAwsSettings.accessKey).

Settings for PrometheusConnectionSettings.sigv4(...).

Which credential to use: "default" picks one from the environment (see PrometheusConnectionSettings.azure); the others are explicit.

Settings for PrometheusConnectionSettings.azure(...).

The server's build information. version is always present; the API notes the other properties may change between versions, so they are optional.

The connection half of every Prometheus call's settings.

A credential source: given the outgoing request and the context's seams, return the headers that authenticate it.

Sources run in the order they were configured, each seeing the headers the earlier ones added, and may not replace a header that is already present. Every returned value is treated as a secret and masked in errors (values shorter than eight characters excepted — see registerSecrets). A source that throws fails the call with a "./errors.ts".PrometheusRequestError whose message is scrubbed the same way. It is called once per request.

A source that caches — a token until its expiry — must keep that cache outside the settings lambda: the lambda runs on every call, so a source created inside it starts empty each time. Define the source once at module level (or key its cache in module state, as the built-in google, azure and sigv4 sources do) and pass that one function to credentials(...).

The seams a credential source reads the outside world through, so a source that reads an environment variable, a key file, the clock or a token endpoint is testable without any of them. Each is set on the connection settings (readEnv, readTextFile, now, fetch).

A target relabelling dropped.

A duration an API parameter accepts: Prometheus duration text such as "5m", or a number of seconds (the API's float form).

What an instant and a range query share: the expression and its limits.

An instant-vector element whose sample is a float (the API's value key).

Settings for PrometheusConnectionSettings.google(...).

Header names to values, as a credential source returns them.

A native histogram value, the API's <histogram> placeholder.

One bucket of a native histogram: [<boundary_rule>, "<left>", "<right>", "<count>"].

One native-histogram sample at a point in time: [<unix_time>, <histogram>].

An instant-vector element whose sample is a native histogram (histogram).

The HTTP method for an endpoint the API serves on both GET and POST.

A label set: label name to label value, as the API's metric object.

Settings for listing label names (/api/v1/labels).

Settings for one label's values (/api/v1/label/<label_name>/values).

A range vector: resultType: "matrix".

Settings for metric metadata (/api/v1/metadata).

One metadata entry for a metric, as scraped from a target.

The outgoing request a PrometheusCredentials source authenticates — exactly what will be sent, so a signature computed over it verifies.

One float sample at a point in time: a [<unix_time>, "<value>"] pair.

The data of an expression query, discriminated on resultType exactly as the API sends it.

Settings for a range query (/api/v1/query_range).

Settings for an instant query (/api/v1/query).

A recording rule.

A Prometheus call produced no usable answer: the request could not be sent or timed out, a credential source failed, or the answer was too large, not JSON, or not shaped as the API reference describes.

A successful API answer: the endpoint's typed data, plus the warnings and infos annotations Prometheus attaches to a result it still returned.

Both arrays are always present — empty when the server sent none — so a gate can fail on warnings.length > 0 without first checking for the key.

A rule, discriminated on type.

Fields every rule carries.

A rule group.

The loaded rules.

Settings for the loaded rules (/api/v1/rules).

The rule kinds /api/v1/rules filters on: the API's type parameter.

A scalar: resultType: "scalar".

What the series, label-name and label-value endpoints share.

One series of a range vector. The API gives a series values, histograms, or both; whichever is absent is an empty array here.

Settings for finding series by matchers (/api/v1/series).

A string: resultType: "string".

The target overview: active and dropped targets.

Settings for the target overview (/api/v1/targets).

Which targets /api/v1/targets returns: the API's state parameter.

The Prometheus HTTP API as tasks (<https://prometheus.io/docs/prometheus/latest/querying/api/>).

The operations PrometheusTasks exposes.

A time an API parameter accepts: a Date, Unix seconds, or RFC 3339 text.

An instant vector: resultType: "vector".

One element of an instant vector. The API gives each element a value or a histogram, never both — narrow with "value" in sample.