tramli-plugins 3.4.0

Plugin pack for tramli — audit, eventstore, observability, resume, idempotency, hierarchy, diagram, docs, lint, testing, subflow
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

use std::sync::{Arc, Mutex};
use std::time::Instant;
use tramli::{FlowEngine, FlowState};
use crate::api::PluginDescriptor;

/// Telemetry event type.
#[derive(Debug, Clone)]
pub enum TelemetryType {
    Transition,
    Guard,
    Error,
    State,
}

/// A telemetry event captured by the observability plugin.
#[derive(Debug, Clone)]
pub struct TelemetryEvent {
    pub event_type: TelemetryType,
    pub flow_id: String,
    pub data: String,
    pub timestamp: Instant,
}

/// Telemetry sink trait.
pub trait TelemetrySink: Send + Sync {
    fn emit(&self, event: TelemetryEvent);
    fn events(&self) -> Vec<TelemetryEvent>;
}

/// In-memory telemetry sink.
pub struct InMemoryTelemetrySink {
    log: Mutex<Vec<TelemetryEvent>>,
}

impl InMemoryTelemetrySink {
    pub fn new() -> Self {
        Self { log: Mutex::new(Vec::new()) }
    }
}

impl Default for InMemoryTelemetrySink {
    fn default() -> Self {
        Self::new()
    }
}

impl TelemetrySink for InMemoryTelemetrySink {
    fn emit(&self, event: TelemetryEvent) {
        self.log.lock().unwrap().push(event);
    }

    fn events(&self) -> Vec<TelemetryEvent> {
        self.log.lock().unwrap().clone()
    }
}

/// Observability engine plugin — installs transition/error logger hooks.
pub struct ObservabilityPlugin {
    sink: Arc<dyn TelemetrySink>,
}

impl ObservabilityPlugin {
    pub fn new(sink: Arc<dyn TelemetrySink>) -> Self {
        Self { sink }
    }

    pub fn descriptor(&self) -> PluginDescriptor {
        PluginDescriptor {
            id: "observability",
            display_name: "Observability",
            description: "Telemetry via engine logger hooks",
        }
    }

    pub fn install<S: FlowState>(&self, engine: &mut FlowEngine<S>) {
        let sink = self.sink.clone();
        engine.set_transition_logger(move |entry| {
            sink.emit(TelemetryEvent {
                event_type: TelemetryType::Transition,
                flow_id: entry.flow_id.clone(),
                data: format!("{} -> {} via {}", entry.from, entry.to, entry.trigger),
                timestamp: Instant::now(),
            });
        });

        let sink = self.sink.clone();
        engine.set_error_logger(move |entry| {
            sink.emit(TelemetryEvent {
                event_type: TelemetryType::Error,
                flow_id: entry.flow_id.clone(),
                data: format!("{} -> {} error: {:?}", entry.from, entry.to, entry.cause),
                timestamp: Instant::now(),
            });
        });

        let sink = self.sink.clone();
        engine.set_guard_logger(move |entry| {
            sink.emit(TelemetryEvent {
                event_type: TelemetryType::Guard,
                flow_id: entry.flow_id.clone(),
                data: format!("guard {} at {}: {}", entry.guard_name, entry.state, entry.result),
                timestamp: Instant::now(),
            });
        });
    }
}