scrapfly_sdk/
monitoring.rs

1//! Monitoring API — aggregated + per-target metrics.
2//!
3//! Wraps `GET /scrape/monitoring/metrics` and
4//! `GET /scrape/monitoring/metrics/target`. Enterprise plan only.
5//! See <https://scrapfly.io/docs/monitoring#api>.
6
7use serde::{Deserialize, Serialize};
8
9/// Response format for the Monitoring API.
10#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
11#[serde(rename_all = "lowercase")]
12pub enum MonitoringDataFormat {
13    /// Structured JSON aggregates (default).
14    Structured,
15    /// Prometheus text exposition.
16    Prometheus,
17}
18
19impl MonitoringDataFormat {
20    /// Wire-format string.
21    pub fn as_str(&self) -> &'static str {
22        match self {
23            Self::Structured => "structured",
24            Self::Prometheus => "prometheus",
25        }
26    }
27}
28
29/// Pre-defined monitoring time window.
30#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
31pub enum MonitoringPeriod {
32    /// Last 5 minutes.
33    #[serde(rename = "last5m")]
34    Last5m,
35    /// Last 1 hour.
36    #[serde(rename = "last1h")]
37    Last1h,
38    /// Last 24 hours.
39    #[serde(rename = "last24h")]
40    Last24h,
41    /// Last 7 days.
42    #[serde(rename = "last7d")]
43    Last7d,
44    /// Current subscription period.
45    #[serde(rename = "subscription")]
46    Subscription,
47}
48
49impl MonitoringPeriod {
50    /// Wire-format string.
51    pub fn as_str(&self) -> &'static str {
52        match self {
53            Self::Last5m => "last5m",
54            Self::Last1h => "last1h",
55            Self::Last24h => "last24h",
56            Self::Last7d => "last7d",
57            Self::Subscription => "subscription",
58        }
59    }
60}
61
62/// Aggregation level for `/scrape/monitoring/metrics`.
63#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
64#[serde(rename_all = "lowercase")]
65pub enum MonitoringAggregation {
66    /// Account-level totals.
67    Account,
68    /// Per-project aggregates.
69    Project,
70    /// Top-100 targets.
71    Target,
72}
73
74impl MonitoringAggregation {
75    /// Wire-format string.
76    pub fn as_str(&self) -> &'static str {
77        match self {
78            Self::Account => "account",
79            Self::Project => "project",
80            Self::Target => "target",
81        }
82    }
83}
84
85/// Options for the request-based metrics endpoints
86/// (`get_*_monitoring_metrics`).
87#[derive(Debug, Clone, Default)]
88pub struct MonitoringMetricsOptions {
89    /// Response format (default: `Structured`).
90    pub format: Option<MonitoringDataFormat>,
91    /// Pre-defined time window.
92    pub period: Option<MonitoringPeriod>,
93    /// Aggregation levels to include (combinable).
94    pub aggregation: Option<Vec<MonitoringAggregation>>,
95    /// Fold events with `origin=WEBHOOK` (callbacks executed by the
96    /// webhook worker) into this product's totals. Defaults to `false`
97    /// to match the dashboard's default view.
98    pub include_webhook: bool,
99}
100
101/// Options for the request-based per-target endpoints
102/// (`get_*_monitoring_target_metrics`).
103///
104/// `start` and `end` are pre-formatted UTC strings in the Scrapfly API
105/// format `YYYY-MM-DD HH:MM:SS`. They are mutually exclusive with `period`
106/// and must be provided together.
107#[derive(Debug, Clone)]
108pub struct MonitoringTargetMetricsOptions {
109    /// Target root domain (e.g. `httpbin.dev`). Required.
110    pub domain: String,
111    /// Group subdomains under the root. Defaults to `false`.
112    pub group_subdomain: bool,
113    /// Pre-defined window. Ignored if `start`/`end` are provided.
114    pub period: Option<MonitoringPeriod>,
115    /// Custom window start (UTC, `YYYY-MM-DD HH:MM:SS`). Must be set with `end`.
116    pub start: Option<String>,
117    /// Custom window end (UTC, `YYYY-MM-DD HH:MM:SS`). Must be set with `start`.
118    pub end: Option<String>,
119    /// Fold WEBHOOK origin into this product's totals.
120    pub include_webhook: bool,
121}
122
123impl MonitoringTargetMetricsOptions {
124    /// Convenience constructor: query a single domain with the default
125    /// pre-defined window.
126    pub fn for_domain(domain: impl Into<String>) -> Self {
127        Self {
128            domain: domain.into(),
129            group_subdomain: false,
130            period: None,
131            start: None,
132            end: None,
133            include_webhook: false,
134        }
135    }
136}
137
138/// Options for the Cloud Browser monitoring endpoints. Cloud Browser is
139/// session-based (one allocation = one long-lived browser, billed by
140/// runtime + bandwidth) and exposes a distinct shape from the
141/// request-based products. There is no `domain`/`target` and no
142/// `include_webhook`.
143#[derive(Debug, Clone, Default)]
144pub struct CloudBrowserMonitoringOptions {
145    /// Pre-defined window. Ignored if `start`/`end` are provided.
146    pub period: Option<MonitoringPeriod>,
147    /// Optional filter to a single proxy pool (e.g. `public_datacenter_pool`).
148    pub proxy_pool: Option<String>,
149    /// Custom window start (UTC, `YYYY-MM-DD HH:MM:SS`). Must be set with `end`.
150    pub start: Option<String>,
151    /// Custom window end (UTC, `YYYY-MM-DD HH:MM:SS`). Must be set with `start`.
152    pub end: Option<String>,
153}
scrapfly_sdk/monitoring.rs

scrapfly_sdk/
monitoring.rs
