scrapfly_sdk/
monitoring.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
//! Monitoring API — aggregated + per-target metrics.
//!
//! Wraps `GET /scrape/monitoring/metrics` and
//! `GET /scrape/monitoring/metrics/target`. Enterprise plan only.
//! See <https://scrapfly.io/docs/monitoring#api>.

use serde::{Deserialize, Serialize};

/// Response format for the Monitoring API.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum MonitoringDataFormat {
    /// Structured JSON aggregates (default).
    Structured,
    /// Prometheus text exposition.
    Prometheus,
}

impl MonitoringDataFormat {
    /// Wire-format string.
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Structured => "structured",
            Self::Prometheus => "prometheus",
        }
    }
}

/// Pre-defined monitoring time window.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum MonitoringPeriod {
    /// Last 5 minutes.
    #[serde(rename = "last5m")]
    Last5m,
    /// Last 1 hour.
    #[serde(rename = "last1h")]
    Last1h,
    /// Last 24 hours.
    #[serde(rename = "last24h")]
    Last24h,
    /// Last 7 days.
    #[serde(rename = "last7d")]
    Last7d,
    /// Current subscription period.
    #[serde(rename = "subscription")]
    Subscription,
}

impl MonitoringPeriod {
    /// Wire-format string.
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Last5m => "last5m",
            Self::Last1h => "last1h",
            Self::Last24h => "last24h",
            Self::Last7d => "last7d",
            Self::Subscription => "subscription",
        }
    }
}

/// Aggregation level for `/scrape/monitoring/metrics`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum MonitoringAggregation {
    /// Account-level totals.
    Account,
    /// Per-project aggregates.
    Project,
    /// Top-100 targets.
    Target,
}

impl MonitoringAggregation {
    /// Wire-format string.
    pub fn as_str(&self) -> &'static str {
        match self {
            Self::Account => "account",
            Self::Project => "project",
            Self::Target => "target",
        }
    }
}

/// Options for the request-based metrics endpoints
/// (`get_*_monitoring_metrics`).
#[derive(Debug, Clone, Default)]
pub struct MonitoringMetricsOptions {
    /// Response format (default: `Structured`).
    pub format: Option<MonitoringDataFormat>,
    /// Pre-defined time window.
    pub period: Option<MonitoringPeriod>,
    /// Aggregation levels to include (combinable).
    pub aggregation: Option<Vec<MonitoringAggregation>>,
    /// Fold events with `origin=WEBHOOK` (callbacks executed by the
    /// webhook worker) into this product's totals. Defaults to `false`
    /// to match the dashboard's default view.
    pub include_webhook: bool,
}

/// Options for the request-based per-target endpoints
/// (`get_*_monitoring_target_metrics`).
///
/// `start` and `end` are pre-formatted UTC strings in the Scrapfly API
/// format `YYYY-MM-DD HH:MM:SS`. They are mutually exclusive with `period`
/// and must be provided together.
#[derive(Debug, Clone)]
pub struct MonitoringTargetMetricsOptions {
    /// Target root domain (e.g. `httpbin.dev`). Required.
    pub domain: String,
    /// Group subdomains under the root. Defaults to `false`.
    pub group_subdomain: bool,
    /// Pre-defined window. Ignored if `start`/`end` are provided.
    pub period: Option<MonitoringPeriod>,
    /// Custom window start (UTC, `YYYY-MM-DD HH:MM:SS`). Must be set with `end`.
    pub start: Option<String>,
    /// Custom window end (UTC, `YYYY-MM-DD HH:MM:SS`). Must be set with `start`.
    pub end: Option<String>,
    /// Fold WEBHOOK origin into this product's totals.
    pub include_webhook: bool,
}

impl MonitoringTargetMetricsOptions {
    /// Convenience constructor: query a single domain with the default
    /// pre-defined window.
    pub fn for_domain(domain: impl Into<String>) -> Self {
        Self {
            domain: domain.into(),
            group_subdomain: false,
            period: None,
            start: None,
            end: None,
            include_webhook: false,
        }
    }
}

/// Options for the Cloud Browser monitoring endpoints. Cloud Browser is
/// session-based (one allocation = one long-lived browser, billed by
/// runtime + bandwidth) and exposes a distinct shape from the
/// request-based products. There is no `domain`/`target` and no
/// `include_webhook`.
#[derive(Debug, Clone, Default)]
pub struct CloudBrowserMonitoringOptions {
    /// Pre-defined window. Ignored if `start`/`end` are provided.
    pub period: Option<MonitoringPeriod>,
    /// Optional filter to a single proxy pool (e.g. `public_datacenter_pool`).
    pub proxy_pool: Option<String>,
    /// Custom window start (UTC, `YYYY-MM-DD HH:MM:SS`). Must be set with `end`.
    pub start: Option<String>,
    /// Custom window end (UTC, `YYYY-MM-DD HH:MM:SS`). Must be set with `start`.
    pub end: Option<String>,
}