Skip to content
Snippets Groups Projects
Commit c9c941c2 authored by Maaz Ahmed's avatar Maaz Ahmed
Browse files

doc: update README

parent 36e50229
No related branches found
No related tags found
1 merge request!15Release: prepare and release 0.5.0
# mquery
`mquery`, short for (M)etrics Query, is a Rust library for handling PROMQL (and possibly MetricsQL) queries.
`mquery`, short for (M)etrics Query, is a Rust library for handling PromQL and MetricsQL queries.
The library internally uses `prometheus-http-query` crate. As the name suggests, mquery is mainly focused on dealing with metrics 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.
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).
The library supports raw queries (strings) as well as typed queries (builder API). The builder API is provided through the type `Metric` and `Scalar` types found in the `query` module. Note that the builder API doesn't prevent you from writing invalid queries, it only helps you avoid errors to a certain degree.
## 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.
Any 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.
A compile time query validation like the one found in the `sqlx` crate is on the roadmap.
## 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
```rust
use mquery::{Auth, QueryManager, query};
use mquery::{
macros::promql,
query::{fns::aggregate::sum, Metric},
result::Error,
Auth, Method, QueryManager,
};
const TOKEN: &str = "";
#[tokio::main]
async fn main() {
dotenv::dotenv().expect("No .env file found in working dir");
let url = std::env::var("VM_URL").expect("VM URL not found in env");
let token = std::env::var("VM_TOKEN").expect("VM token not found in env");
let query = query::Metric::new("total_http_requests").label_eq("method", "get");
let _response = QueryManager::new(url.parse().unwrap())
.auth(Auth::Bearer(token))
.query(query)
.await
.expect("operation failed");
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
let checked_qry = promql!(sum(metric_name{label="value",label2!="value2"}));
let _response = manager.query(checked_qry).await?;
// 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
When you keep getting the error `Client(ClientError("failed to parse response from server due to invalid media type"))` and cannot figure out what might be wrong, it is likely that the server URL is the culprit. Ensure that only the base URL to the server is passed to the `QueryManager` which shouldn't contain the API endpoint path like `/api/v1/query`.
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.
......@@ -47,4 +65,4 @@ Requires a local Victoria Metrics server running at `http://127.0.0.1:8428/` for
- [x] Compile time syntax checking
- [x] ~~Deserialize~~ Convert to custom data types
- [ ] ORM-like API to build queries using user defined types (derive macro)
- [ ] Processing multiple queries at once
- [x] Processing multiple queries at once (only instant queries for now)
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment