shared-framework 0.0.17

//! Log monitoring events and sinks.
//!
//! [`MonitoringEvent`] is the structured record emitted for a log entry and
//! [`ILogMonitor`] is the async sink that receives and flushes those events.
//!
//! ```ignore
//! let event = MonitoringEvent {
//!     event_id: "evt-1".to_string(),
//!     timestamp: chrono::Utc::now(),
//!     duration_ms: None,
//!     level: LogLevel::Info,
//!     message: "started".to_string(),
//!     data: None,
//!     correlation_id: ctx.correlation_id(),
//! };
//! monitor.log(event).await?;
//! ```

use chrono::{DateTime, Utc};
use serde::{Deserialize, Serialize};

/// Severity of a [`MonitoringEvent`].
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum LogLevel {
    /// Command execution.
    Exec,
    /// Failures.
    Error,
    /// Noteworthy normal events.
    Info,
    /// Diagnostic detail.
    Debug,
    /// Potential problems.
    Warn,
    /// Timed-operation records.
    Time,
}

/// Structured log record sent to an [`ILogMonitor`].
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MonitoringEvent {
    /// Unique ID of this event.
    pub event_id: String,
    /// When the event occurred.
    pub timestamp: DateTime<Utc>,
    /// Operation duration, when the event measures timed work.
    pub duration_ms: Option<u64>,
    /// Severity of the event.
    pub level: LogLevel,
    /// Human-readable message.
    pub message: String,
    /// Optional structured payload.
    pub data: Option<serde_json::Value>,
    /// Correlation ID of the request that produced the event.
    pub correlation_id: String,
}

/// Async sink for [`MonitoringEvent`] records.
#[async_trait::async_trait]
pub trait ILogMonitor: Send + Sync {
    /// Receives one monitoring event. Returns an error if the event cannot be recorded.
    async fn log(&self, event: MonitoringEvent) -> anyhow::Result<()>;
    /// Flushes any buffered events. Returns an error if the flush fails.
    async fn flush(&self) -> anyhow::Result<()>;
}