mquery

mquery, short for (M)etrics Query, is a Rust library for handling PromQL and MetricsQL queries.

Write raw queries (strings) or use typed queries (builder API). The builder API is provided through the Metric and Scalar types found in the query module. Note that the builder API doesn't entirely prevent you from writing invalid queries, it only helps you avoid errors to a certain degree (use the promql macro for compile time query validation).

Feature Flags

• utils - Additional utilities related to handling and processing the query data can be found in the utils module which is placed under the utils feature flag. This module currently includes the Convert trait, which let's you convert the response data containing labels as HashMap<String, String> to a data type with custom defined label structs.
• metricsql - Enables any types and functionality of the builder API that's specific to MetricsQL (types related to MetricsQL also generally are prefixed with mql)
• multi - Enables a method on the QueryManager for handling multiple queries at once (currently only instant queries as supported)
• macros - Enables any procedural macros that ship with the crate. As of version 0.5.0, this module only includes the promql macro for compile time query validation.

Internal implementation

The library internally uses prometheus-http-query crate. As the name suggests, mquery is mainly focused on dealing with metric queries and the resulting data, and nothing else. The aforementioned library is better suited when functionality related to the full HTTP API offered by Prometheus and other compatible solutions is required.

Usage Example

use mquery::{
    query::{fns::aggregate::sum, Metric},
    result::Error,
    Auth, Method, QueryManager,
};

#[cfg(feature = "macros")]
use mquery::macros::promql;

const TOKEN: &str = "";

#[tokio::main]
async fn main() -> Result<(), Error> {
    let url = "http://domain.com/prometheus";

    let mut manager = QueryManager::new(url.parse().unwrap()); // The client
    manager // Configure the client
        .auth(Auth::Bearer(TOKEN.to_owned())) // supports bearer auth
        .timeout(20)
        .method(Method::Post); // Default is `GET`

    // Compile time checked queries
    #[cfg(feature = "macros")]
    let checked_qry = promql!(sum(metric_name{label="value",label2!="value2"}));

    // Query builder API
    let typed_query = sum(Metric::new("metric_name")
        .label_eq("label", "value")
        .label_ne("label2", "value2"));
    let _response = manager.query(typed_query).await;

    Ok(())
}

Debugging

If you keep getting the error Client(ClientError("failed to parse response from server due to invalid media type")) and cannot trace the source of the issue, ensure that only the base URL to the server is passed to the QueryManager which shouldn't contain the API endpoint path (i.e. /api/v1/query).

Testing

Requires a local Victoria Metrics server running at http://127.0.0.1:8428/ for the integration tests to work.

Roadmap

• Basic raw queries (Instant and Ranged)
• Query Builder
  • Basic queries
  • Operators
    • Binary Operators
    • Vector matching
    • Aggregation operators (implemented as functions)
  • Functions (initial support for most important fns)
• Runtime syntax checking (?)
• Compile time syntax checking
• Deserialize Convert to custom data types
• ORM-like API to build queries using user defined types (derive macro)
• Processing multiple queries at once (only instant queries for now)