Crate prometheus_http_query

The goal of this crate is to provide a query interface to the Prometheus HTTP API and leverage Rust’s type system in the process. Thus mistakes while building a query can be caught at compile-time (or at least before actually sending the query to Prometheus).

Most of the features of PromQL are mirrored in this library. Queries are gradually built from time series selectors, aggregations and functions and then passed to an HTTP client to execute.

Behind the scenes this library uses the reqwest crate as a HTTP client. Thus its features and limitations also apply to this library.

Usage

use prometheus_http_query::{Client, Selector, RangeVector, Aggregate};
use prometheus_http_query::aggregations::sum;
use prometheus_http_query::functions::rate;
use std::convert::TryInto;

#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), prometheus_http_query::Error> {
    let client: Client = Default::default();

    let v: RangeVector = Selector::new()
        .metric("node_cpu_seconds_total")?
        .with("mode", "user")
        .range("5m")?
        .try_into()?;

    let q = sum(rate(v), Some(Aggregate::By(&["cpu"])));

    let response = client.query(q, None, None).await;

    assert!(response.is_ok());

    // It is also possible to bypass every kind of validation by supplying
    // a custom query directly to the InstantVector | RangeVector types.
    // The equivalent of the operation above would be:
    let q = r#"sum by(cpu) (rate(node_cpu_seconds_total{mode="user"}[5m]))"#;

    let v = RangeVector(q.to_string());

    let response = client.query(v, None, None).await;

    assert!(response.is_ok());
    
    Ok(())
}

Notes

If the JSON response from the Prometheus HTTP API indicates an error (field status == "error"), then the contents of both fields errorType and error are captured and then returned by the client as a variant of the Error enum, just as any HTTP errors (non-200) that may indicate a problem with the provided query string. Thus any syntax problems etc. that cannot be caught at compile time or before executing the query will at least be propagated in the same manner.

Limitations

• Metadata queries (series/labels) are not supported (yet)
• reqwest client configuration cannot be customized (yet)
• Subqueries are not supported (only as custom query)
• PromQL functions that do not take a range / instant vector as an argument are not supported (only as custom query)

Modules

aggregations	A set of aggregation operators like sum and avg
functions	A set of PromQL function equivalents e.g. abs and rate

Structs

Client	A client used to execute queries. It uses a reqwest::Client internally that manages connections for us.
InstantVector	An instant vector expression that can be further operated on with functions/aggregations or passed to a crate::Client in order to evaluate.
Matrix	A single time series containing a range of data points (Samples).
RangeVector	An range vector expression that can be further operated on with functions/aggregations or passed to a Client in order to evaluate.
Sample	A single data point.
Selector	A time series selector that is gradually built from a metric name and/or a set of label matchers.
Vector	A single time series containing a single data point (Sample).

Enums

Aggregate	A helper type that provides label matching logic for e.g. aggregations like sum.
Error	A global error enum that encapsulates other more specific types of errors.
Group	A helper type that provides grouping logic for e.g. vector matching.
Match	A helper type that provides label matching logic for e.g. binary operations (between instant vectors).
Response	A response wrapper for vector and matrix return types. The Vector and Matrix types encapsulate a set of time series with a single sample and a set of time series containing a range of sample data respectively.
Scheme	A helper enum that is passed to the Client::new function in order to avoid errors on unsupported connection schemes.