prometheus_http_client/
lib.rs

1#![deny(missing_docs)]
2
3//! Minimal API for getting time series data from prometheus, and making small plots.
4//!
5//! To use it, instantiate one of the request objects,
6//! e.g. QueryRequest or QueryRangeRequest. When it's helpful a builder is provided.
7//!
8//! Then use `PromRequest` trait and call `send` or `send_with_client`.
9//! This takes the prometheus url, and optionally a reqwest client to use.
10//!
11//! On success, the result is `PromData`. One would usually call `into_matrix()?`
12//! or `into_vector()?` as expected for the request that is made.
13//!
14//! In prometheus, metric labels are just a set of key-value pairs. However,
15//! if you are expecting certain structure, you may use any KV object that implements
16//! `serde::Deserialize` in the `PromData` that results from the call.
17//!
18//! When `plot` feature is active, the plot module can be used to plot the timeseries data.
19//! This was designed to be used to generate previews in alert messages.
20
21pub use reqwest::Client as ReqwestClient;
22
23use chrono::{DateTime, Utc};
24use serde::{Serialize, de::DeserializeOwned};
25use std::fmt::Debug;
26
27mod builders;
28pub use builders::QueryRangeRequestBuilder;
29
30mod error;
31pub use error::Error;
32
33mod labels;
34pub use labels::{ExtractLabels, Labels};
35
36mod messages;
37use messages::PromResponse;
38pub use messages::{
39    AlertInfo, AlertStatus, AlertsResponse, MetricTimeseries, MetricVal, MetricValue, PromData,
40};
41
42#[cfg(feature = "plot")]
43pub mod plot;
44
45mod traits;
46pub use traits::PromRequest;
47
48/// Query parameters for /api/v1/query prometheus request
49#[derive(Clone, Debug, Serialize)]
50pub struct QueryRequest {
51    /// The PromQL query string
52    pub query: String,
53    /// Optional evaluation timestamp (defaults to current time)
54    pub time: Option<DateTime<Utc>>,
55}
56
57impl PromRequest for QueryRequest {
58    const PATH: &str = "/api/v1/query";
59    type Output<KV: Clone + Debug + DeserializeOwned> = PromData<KV>;
60}
61
62/// Query parameters for /api/v1/query_range prometheus request
63/// Use builder to populate it
64#[derive(Clone, Debug, Serialize)]
65pub struct QueryRangeRequest {
66    query: String,
67    start: DateTime<Utc>,
68    end: DateTime<Utc>,
69    step: f64,
70}
71
72impl QueryRangeRequest {
73    /// Get builder for query range request with given query
74    pub fn builder(query: impl Into<String>) -> QueryRangeRequestBuilder {
75        QueryRangeRequestBuilder::new(query.into())
76    }
77}
78
79impl PromRequest for QueryRangeRequest {
80    const PATH: &str = "/api/v1/query_range";
81    type Output<KV: Clone + Debug + DeserializeOwned> = PromData<KV>;
82}
83
84/// Query parameters for /api/v1/series prometheus request
85#[derive(Clone, Debug, Serialize)]
86#[serde(transparent)]
87pub struct SeriesRequest {
88    /// Series selector arguments
89    pub matches: MatchList,
90}
91
92impl PromRequest for SeriesRequest {
93    const PATH: &str = "/api/v1/series";
94    type Output<KV: Clone + Debug + DeserializeOwned> = Vec<KV>;
95}
96
97/// Query parameters for /api/v1/labels prometheus request
98#[derive(Clone, Debug, Serialize)]
99#[serde(transparent)]
100pub struct LabelsRequest {
101    /// Series selector arguments to filter which labels are returned
102    pub matches: MatchList,
103}
104
105impl PromRequest for LabelsRequest {
106    const PATH: &str = "/api/v1/labels";
107    type Output<KV: Clone + Debug + DeserializeOwned> = Vec<String>;
108}
109
110/// Query parameters for /api/v1/alerts prometheus request
111#[derive(Clone, Debug, Serialize)]
112pub struct AlertsRequest {}
113
114impl PromRequest for AlertsRequest {
115    const PATH: &str = "/api/v1/alerts";
116    type Output<KV: Clone + Debug + DeserializeOwned> = AlertsResponse<KV>;
117}
118
119/// Represents a sequence of match[]=...,match[]=...
120/// query parameters required by parts of prometheus api
121#[derive(Clone, Debug)]
122pub struct MatchList(Vec<String>);
123
124impl Serialize for MatchList {
125    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
126    where
127        S: serde::Serializer,
128    {
129        use serde::ser::SerializeMap;
130        let mut map = serializer.serialize_map(Some(self.0.len()))?;
131        for v in &self.0 {
132            map.serialize_entry("match[]", v)?;
133        }
134        map.end()
135    }
136}
137
138impl From<Vec<String>> for MatchList {
139    fn from(src: Vec<String>) -> Self {
140        Self(src)
141    }
142}
143
144impl FromIterator<String> for MatchList {
145    fn from_iter<T>(iter: T) -> Self
146    where
147        T: IntoIterator<Item = String>,
148    {
149        Self(iter.into_iter().collect())
150    }
151}
prometheus_http_client/lib.rs

prometheus_http_client/
lib.rs
