Skip to main content

yaiko_core/
task_observability.rs

1//! Structured observability for scheduled task outcomes.
2
3use crate::{MetricKind, MetricsRegistry};
4use std::collections::BTreeMap;
5use std::sync::{Arc, Mutex};
6
7#[derive(Debug, Clone, PartialEq, Eq)]
8pub enum TaskOutcome {
9    Scheduled,
10    Claimed,
11    Completed,
12    Retried,
13    Misfired,
14    Cancelled,
15    Failed,
16}
17
18#[derive(Debug, Clone, PartialEq, Eq)]
19pub struct TaskObservation {
20    pub task_id: String,
21    pub task_name: String,
22    pub outcome: TaskOutcome,
23    pub attempt: u32,
24    pub correlation_id: Option<String>,
25    pub error_code: Option<String>,
26}
27
28#[derive(Clone)]
29pub struct TaskObserver {
30    events: Arc<Mutex<Vec<TaskObservation>>>,
31    capacity: usize,
32    metrics: MetricsRegistry,
33}
34
35impl TaskObserver {
36    pub fn new(capacity: usize) -> Self {
37        let metrics = MetricsRegistry::new();
38        let _ = metrics.define(
39            "task_outcomes",
40            MetricKind::Counter,
41            &["task", "outcome"],
42            capacity.max(1),
43        );
44        Self {
45            events: Arc::new(Mutex::new(Vec::new())),
46            capacity,
47            metrics,
48        }
49    }
50    pub fn record(&self, observation: TaskObservation) {
51        let outcome = match observation.outcome {
52            TaskOutcome::Scheduled => "scheduled",
53            TaskOutcome::Claimed => "claimed",
54            TaskOutcome::Completed => "completed",
55            TaskOutcome::Retried => "retried",
56            TaskOutcome::Misfired => "misfired",
57            TaskOutcome::Cancelled => "cancelled",
58            TaskOutcome::Failed => "failed",
59        };
60        let labels = BTreeMap::from([
61            (String::from("task"), observation.task_name.clone()),
62            (String::from("outcome"), outcome.to_string()),
63        ]);
64        let _ = self.metrics.increment("task_outcomes", &labels, 1);
65        let mut events = self.events.lock().expect("task observer poisoned");
66        if self.capacity == 0 {
67            return;
68        }
69        if events.len() >= self.capacity {
70            events.remove(0);
71        }
72        events.push(observation);
73    }
74    pub fn events(&self) -> Vec<TaskObservation> {
75        self.events.lock().expect("task observer poisoned").clone()
76    }
77    pub fn metrics(&self) -> crate::MetricsSnapshot {
78        self.metrics.snapshot()
79    }
80}
81
82#[cfg(test)]
83mod tests {
84    use super::*;
85
86    fn observation(outcome: TaskOutcome) -> TaskObservation {
87        TaskObservation {
88            task_id: "t1".into(),
89            task_name: "render".into(),
90            outcome,
91            attempt: 1,
92            correlation_id: Some("req-1".into()),
93            error_code: None,
94        }
95    }
96
97    #[test]
98    fn records_bounded_task_history_and_metrics() {
99        let observer = TaskObserver::new(2);
100        observer.record(observation(TaskOutcome::Scheduled));
101        observer.record(observation(TaskOutcome::Completed));
102        observer.record(observation(TaskOutcome::Misfired));
103        assert_eq!(observer.events().len(), 2);
104        assert_eq!(observer.events()[0].outcome, TaskOutcome::Completed);
105        assert!(!observer.metrics().values.is_empty());
106    }
107
108    #[test]
109    fn preserves_retry_and_correlation_metadata() {
110        let observer = TaskObserver::new(3);
111        let mut retry = observation(TaskOutcome::Retried);
112        retry.attempt = 3;
113        retry.error_code = Some("timeout".into());
114        observer.record(retry);
115        assert_eq!(observer.events()[0].attempt, 3);
116        assert_eq!(
117            observer.events()[0].correlation_id.as_deref(),
118            Some("req-1")
119        );
120        assert_eq!(observer.events()[0].error_code.as_deref(), Some("timeout"));
121    }
122}