azoth-core 0.2.5

Core traits and types for the Azoth embedded database
Documentation 
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

//! Optional metrics instrumentation for Azoth.
//!
//! When the `observe` feature is enabled, key operations emit counters,
//! histograms, and gauges via the [`metrics`] crate. A downstream
//! application must install a metrics recorder (e.g. `metrics-exporter-prometheus`)
//! to collect the data.
//!
//! When the feature is **not** enabled every function in this module is a
//! zero-cost no-op.

/// Record a transaction commit (counter + latency histogram).
///
/// - `azoth.transaction.commits_total` – incremented on every commit
/// - `azoth.transaction.commit_duration_seconds` – histogram of commit latency
#[inline]
pub fn record_commit(duration: std::time::Duration) {
    #[cfg(feature = "observe")]
    {
        metrics::counter!("azoth.transaction.commits_total").increment(1);
        metrics::histogram!("azoth.transaction.commit_duration_seconds")
            .record(duration.as_secs_f64());
    }
    #[cfg(not(feature = "observe"))]
    {
        let _ = duration;
    }
}

/// Record a preflight validation (counter + duration).
///
/// - `azoth.preflight.total` – counter
/// - `azoth.preflight.duration_seconds` – histogram
#[inline]
pub fn record_preflight(duration: std::time::Duration, success: bool) {
    #[cfg(feature = "observe")]
    {
        let outcome = if success { "ok" } else { "fail" };
        metrics::counter!("azoth.preflight.total", "outcome" => outcome).increment(1);
        metrics::histogram!("azoth.preflight.duration_seconds").record(duration.as_secs_f64());
    }
    #[cfg(not(feature = "observe"))]
    {
        let _ = (duration, success);
    }
}

/// Record a preflight cache hit or miss.
///
/// - `azoth.preflight_cache.lookups_total` – counter with `result` label (`hit` / `miss`)
#[inline]
pub fn record_cache_lookup(hit: bool) {
    #[cfg(feature = "observe")]
    {
        let result = if hit { "hit" } else { "miss" };
        metrics::counter!("azoth.preflight_cache.lookups_total", "result" => result).increment(1);
    }
    #[cfg(not(feature = "observe"))]
    {
        let _ = hit;
    }
}

/// Set the current preflight cache size gauge.
///
/// - `azoth.preflight_cache.size` – gauge
#[inline]
pub fn set_cache_size(size: usize) {
    #[cfg(feature = "observe")]
    {
        metrics::gauge!("azoth.preflight_cache.size").set(size as f64);
    }
    #[cfg(not(feature = "observe"))]
    {
        let _ = size;
    }
}

/// Record a projector run (counter + duration + events processed).
///
/// - `azoth.projector.runs_total` – counter
/// - `azoth.projector.run_duration_seconds` – histogram
/// - `azoth.projector.events_processed_total` – counter
#[inline]
pub fn record_projector_run(duration: std::time::Duration, events_processed: u64) {
    #[cfg(feature = "observe")]
    {
        metrics::counter!("azoth.projector.runs_total").increment(1);
        metrics::histogram!("azoth.projector.run_duration_seconds").record(duration.as_secs_f64());
        metrics::counter!("azoth.projector.events_processed_total").increment(events_processed);
    }
    #[cfg(not(feature = "observe"))]
    {
        let _ = (duration, events_processed);
    }
}

/// Record a lock acquisition wait time.
///
/// - `azoth.lock.wait_duration_seconds` – histogram
#[inline]
pub fn record_lock_wait(duration: std::time::Duration) {
    #[cfg(feature = "observe")]
    {
        metrics::histogram!("azoth.lock.wait_duration_seconds").record(duration.as_secs_f64());
    }
    #[cfg(not(feature = "observe"))]
    {
        let _ = duration;
    }
}

/// Record a backup operation.
///
/// - `azoth.backup.total` – counter with `outcome` label
/// - `azoth.backup.duration_seconds` – histogram
#[inline]
pub fn record_backup(duration: std::time::Duration, success: bool) {
    #[cfg(feature = "observe")]
    {
        let outcome = if success { "ok" } else { "fail" };
        metrics::counter!("azoth.backup.total", "outcome" => outcome).increment(1);
        metrics::histogram!("azoth.backup.duration_seconds").record(duration.as_secs_f64());
    }
    #[cfg(not(feature = "observe"))]
    {
        let _ = (duration, success);
    }
}