clawdesk-telemetry

Telemetry system for exporting structured events via OTLP (OpenTelemetry Protocol). Provides higher-level event abstractions built on top of clawdesk-observability, focusing on business-level events like message processing, model usage, and error tracking.

Dependencies

Internal: clawdesk-types, clawdesk-observability

External: opentelemetry, opentelemetry-otlp, serde, tracing, tokio

Modules

Module	Description
export	OTLP exporter configuration and batching
events	Structured event definitions for business telemetry
collector	Event collection and aggregation

Key Types

/// Structured telemetry event
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TelemetryEvent {
    pub name: String,
    pub timestamp: chrono::DateTime<chrono::Utc>,
    pub severity: Severity,
    pub attributes: HashMap<String, serde_json::Value>,
    pub resource: ResourceInfo,
}

/// Event severity levels
#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
pub enum Severity {
    Trace,
    Debug,
    Info,
    Warn,
    Error,
    Fatal,
}

/// OTLP exporter
pub struct OtlpExporter {
    endpoint: String,
    batch_size: usize,
    flush_interval: std::time::Duration,
}

impl OtlpExporter {
    pub async fn export(&self, events: &[TelemetryEvent]) -> Result<(), TelemetryError> {
        // Batch and send to OTLP endpoint
    }
}

/// Pre-defined event constructors
pub mod events {
    pub fn message_processed(session_id: &str, model: &str, tokens: u64) -> TelemetryEvent { /* ... */ }
    pub fn provider_error(provider: &str, error: &str) -> TelemetryEvent { /* ... */ }
    pub fn session_created(session_id: &str, channel: &str) -> TelemetryEvent { /* ... */ }
    pub fn fallback_triggered(from: &str, to: &str, reason: &str) -> TelemetryEvent { /* ... */ }
}

Example Usage

use clawdesk_telemetry::{OtlpExporter, events};

let exporter = OtlpExporter::new("http://localhost:4317", 100, Duration::from_secs(5));

// Emit structured events
let event = events::message_processed("sess_abc", "claude-sonnet-4-20250514", 256);
exporter.export(&[event]).await?;

// Track provider errors
let error_event = events::provider_error("openai", "rate_limited");
exporter.export(&[error_event]).await?;

info

clawdesk-telemetry handles business-level events while clawdesk-observability handles infrastructure-level tracing and metrics. Use both together for full observability.