use std::sync::{Arc, Mutex, MutexGuard};
use std::time::Instant;
use super::broker::{
AuditAction, Broker, BrokerError, Reach, RegisteredHandle, Scope, Subject, TapEvent, TapId,
};
use super::capability::assert_capability;
use super::ensure;
use super::governance::{GovernanceError, GovernanceQuery, GovernanceStore};
use super::protocol::{Attribution, AttributionKind, GovernanceEntry, SignalEnvelope, SourceKind};
use super::time::format_millis;
use crate::canvas_protocol::Capability;
mod ring;
pub use ring::{LatencyTracker, RingBuffer, TelemetryMetrics};
#[derive(Clone, Debug, PartialEq, Eq, lgwks_macros::Error)]
#[non_exhaustive]
pub enum TelemetryError {
#[error("telemetry append failed: {0}")]
AppendFailed(String),
#[error("invalid ring capacity: {0}")]
InvalidCapacity(usize),
#[error("ring capacity {0} is past the bound")]
CapacityTooLarge(usize),
#[error("tap release refused: {0}")]
UntapRefused(BrokerError),
}
pub const MAX_RING_CAPACITY: usize = 5_000;
#[derive(Clone)]
pub struct TelemetryTap {
inner: Arc<Mutex<TapInner>>,
}
struct TapInner {
ring: RingBuffer<SignalEnvelope>,
latency: LatencyTracker,
emits_observed: u64,
append_errors: u64,
running: bool,
tap_id: Option<TapId>,
owner: Option<RegisteredHandle>,
governance: GovernanceStore,
granted: Vec<Capability>,
last_error: Option<TelemetryError>,
}
impl TapInner {
fn fail(&mut self, error: TelemetryError) {
self.append_errors = self.append_errors.wrapping_add(1);
self.last_error = Some(error);
}
}
impl TelemetryTap {
pub fn new(
governance: GovernanceStore,
granted: Vec<Capability>,
ring_capacity: usize,
) -> Result<Self, TelemetryError> {
ensure(ring_capacity <= MAX_RING_CAPACITY, || {
TelemetryError::CapacityTooLarge(ring_capacity)
})?;
Ok(Self {
inner: Arc::new(Mutex::new(TapInner {
ring: RingBuffer::new(ring_capacity)?,
latency: LatencyTracker::new(),
emits_observed: 0,
append_errors: 0,
running: false,
tap_id: None,
owner: None,
governance,
granted,
last_error: None,
})),
})
}
fn lock(&self) -> MutexGuard<'_, TapInner> {
lock_inner(&self.inner)
}
pub fn start(&self, broker: &Broker, caller: &RegisteredHandle) -> Result<(), BrokerError> {
let admitted = {
let mut tap = self.lock();
if tap.running {
return Ok(());
}
assert_capability(&tap.granted, Capability::SignalSubscribe).map(|()| {
tap.running = true;
})
};
admitted.map_err(|refusal| {
let denial = BrokerError::from(refusal);
let action = AuditAction::Register(Subject::Tap);
broker.deny_handle(caller, action, &denial);
denial
})?;
let inner = Arc::clone(&self.inner);
let tapped = broker.tap(
caller,
Reach::Own,
Arc::new(move |event: TapEvent| {
handle_tap_event(&inner, &event);
}),
);
let mut tap = self.lock();
match tapped {
Ok(id) => {
tap.tap_id = Some(id);
tap.owner = Some(caller.clone());
Ok(())
}
Err(error) => {
tap.running = false;
Err(error)
}
}
}
pub fn stop(&self, broker: &Broker) {
let mut tap = self.lock();
if !tap.running {
return;
}
tap.running = false;
let (id, owner) = (tap.tap_id.take(), tap.owner.take());
drop(tap);
if let (Some(id), Some(owner)) = (id, owner)
&& let Err(refusal) = broker.untap(&owner, &id)
{
self.lock().last_error = Some(TelemetryError::UntapRefused(refusal));
}
}
#[must_use]
pub fn last_error(&self) -> Option<TelemetryError> {
self.lock().last_error.clone()
}
#[must_use]
pub fn snapshot(&self, session_id: Option<&str>) -> Vec<SignalEnvelope> {
let all = self.lock().ring.snapshot();
match session_id {
None => all,
Some(session) => all
.into_iter()
.filter(|envelope| envelope.session_invariant().session_id() == session)
.collect(),
}
}
#[must_use]
pub fn metrics(&self) -> TelemetryMetrics {
let tap = self.lock();
TelemetryMetrics::new(
tap.emits_observed,
tap.append_errors,
tap.latency.p99_microseconds(),
)
}
}
fn lock_inner(inner: &Mutex<TapInner>) -> MutexGuard<'_, TapInner> {
match inner.lock() {
Ok(guard) => guard,
Err(poisoned) => poisoned.into_inner(),
}
}
fn handle_tap_event(inner: &Arc<Mutex<TapInner>>, event: &TapEvent) {
let started = Instant::now();
let mut tap = lock_inner(inner);
if !tap.running {
return;
}
tap.ring.push(event.envelope().clone());
tap.emits_observed = tap.emits_observed.wrapping_add(1);
let elapsed = started.elapsed().as_nanos().min(u128::from(u64::MAX));
let elapsed_bytes = elapsed.to_le_bytes();
tap.latency.record(u64::from_le_bytes([
elapsed_bytes[0],
elapsed_bytes[1],
elapsed_bytes[2],
elapsed_bytes[3],
elapsed_bytes[4],
elapsed_bytes[5],
elapsed_bytes[6],
elapsed_bytes[7],
]));
let entry = match governance_entry_from_envelope(event.envelope(), event.timestamp_ms()) {
Ok(entry) => entry,
Err(error) => {
tap.fail(TelemetryError::AppendFailed(format!(
"no entry id: {error:?}"
)));
return;
}
};
let governance = tap.governance.clone();
drop(tap);
let policy = event
.envelope()
.session_invariant()
.policy_bundle_id()
.to_owned();
if let Err(error) = governance.append_with_policy(&entry, policy) {
lock_inner(inner).fail(TelemetryError::AppendFailed(format!("{error}")));
}
}
fn governance_entry_from_envelope(
envelope: &SignalEnvelope,
tap_now_ms: u64,
) -> Result<GovernanceEntry, lgwks_std::random::EntropyError> {
let mut entry = GovernanceEntry::new(
envelope.session_invariant().session_id().to_owned(),
lgwks_std::id::Uuid::new_v4()?.to_string(),
envelope.session_invariant().work_object_id().to_owned(),
envelope.signal_id().to_owned(),
envelope.kind().to_owned(),
String::from("telemetry tap capture"),
Attribution::new(
map_source_kind(envelope.source_kind()),
envelope.source_id().to_owned(),
None,
None,
),
);
entry.set_recorded_at(format_millis(tap_now_ms));
entry.set_tenant_id(envelope.session_invariant().tenant_id().to_owned());
Ok(entry)
}
fn map_source_kind(kind: SourceKind) -> AttributionKind {
match kind {
SourceKind::Widget => AttributionKind::Widget,
SourceKind::Ml => AttributionKind::Ml,
SourceKind::System => AttributionKind::System,
SourceKind::User => AttributionKind::User,
}
}
#[derive(Debug, Clone)]
pub struct TapeReader {
store: GovernanceStore,
}
impl TapeReader {
#[must_use]
pub fn new(store: GovernanceStore) -> Self {
Self { store }
}
pub fn recent_entries(
&self,
scope: &Scope,
limit: usize,
window_hours: f64,
now_ms: u64,
) -> Result<Vec<super::governance::GovernanceEntrySnapshot>, GovernanceError> {
let clamped_window = if window_hours.is_finite() && window_hours > 0.0 {
window_hours.min(24.0)
} else {
0.0
};
let window_millis = millis_from_hours(clamped_window);
let from_ms = now_ms.saturating_sub(window_millis);
let query = GovernanceQuery::new(
String::from(scope.tenant_id()),
String::from(scope.session_id()),
from_ms,
now_ms,
None,
None,
)?;
self.store.recent(&query, limit)
}
}
fn millis_from_hours(hours: f64) -> u64 {
trunc_to_u64(hours * 3_600_000.0)
}
fn trunc_to_u64(hours: f64) -> u64 {
if !hours.is_finite() || hours <= 0.0 {
return 0;
}
if hours >= 9_007_199_254_740_992.0 {
return u64::MAX;
}
let bits = hours.to_bits();
let biased = (bits >> 52) & 0x7ff;
if biased < 1023 {
return 0;
}
let shift = biased.wrapping_sub(1023);
let mantissa = (bits & 0x000f_ffff_ffff_ffff) | (1_u64 << 52);
if shift >= 52 {
let amount_bytes = shift.wrapping_sub(52).to_le_bytes();
let amount = u32::from_le_bytes([
amount_bytes[0],
amount_bytes[1],
amount_bytes[2],
amount_bytes[3],
]);
mantissa.wrapping_shl(amount)
} else {
let amount_bytes = 52_u64.wrapping_sub(shift).to_le_bytes();
let amount = u32::from_le_bytes([
amount_bytes[0],
amount_bytes[1],
amount_bytes[2],
amount_bytes[3],
]);
mantissa.wrapping_shr(amount)
}
}