cencori 1.4.0

Official Rust SDK for Cencori - AI Infrastructure for Production
Documentation
/// Telemetry module for reporting web traffic to the Cencori dashboard.
///
/// Logs appear under the project's "Web Gateway" tab with your app's
/// real domain as the host.
use std::sync::Arc;

use crate::client::InnerClient;
use crate::types::WebTelemetryPayload;

/// Module for reporting telemetry data to Cencori.
///
/// All methods are fire-and-forget — they never throw and never block
/// your application. If the request fails, the error is silently
/// swallowed so it cannot disrupt your app's critical path.
#[derive(Debug, Clone)]
pub struct TelemetryModule {
    inner: Arc<InnerClient>,
}

impl TelemetryModule {
    pub(crate) fn new(inner: Arc<InnerClient>) -> Self {
        Self { inner }
    }

    /// Report a web request to the Cencori dashboard.
    ///
    /// Fire-and-forget — this method never throws and never blocks
    /// your application. If the request fails, the error is silently
    /// swallowed so it cannot disrupt your app's critical path.
    ///
    /// # Arguments
    ///
    /// * `payload` - Web request details to log.
    ///
    /// # Example
    ///
    /// ```rust,no_run
    /// use cencori::Cencori;
    /// use cencori::types::WebTelemetryPayload;
    ///
    /// let cencori = Cencori::new(Some("csk_..."), None, None).unwrap();
    /// cencori.telemetry.report_web_request(WebTelemetryPayload {
    ///     host: "my-app.example.com".into(),
    ///     method: "GET".into(),
    ///     path: "/api/chat".into(),
    ///     status_code: 200,
    ///     request_id: None,
    ///     query_string: None,
    ///     message: None,
    ///     user_agent: None,
    ///     referer: None,
    ///     ip_address: None,
    ///     country_code: None,
    ///     latency_ms: None,
    /// });
    /// ```
    pub fn report_web_request(&self, payload: WebTelemetryPayload) {
        let url = self.inner.url("/api/v1/telemetry/web");

        let result = self.inner.blocking_client.post(&url).json(&payload).send();

        if let Err(e) = result {
            log_warn(&format!("Telemetry request failed: {e}"));
        }
    }

    /// Report a web request asynchronously.
    ///
    /// Fire-and-forget — this method never throws and never blocks
    /// your application. If the request fails, the error is silently
    /// swallowed so it cannot disrupt your app's critical path.
    pub async fn async_report_web_request(&self, payload: WebTelemetryPayload) {
        let url = self.inner.url("/api/v1/telemetry/web");

        let result = self
            .inner
            .http_client
            .post(&url)
            .json(&payload)
            .send()
            .await;

        if let Err(e) = result {
            log_warn(&format!("Telemetry request failed: {e}"));
        }
    }
}

/// Minimal log function — uses `eprintln!` when no logging crate is available.
/// This is intentional: telemetry errors must never crash the app.
fn log_warn(message: &str) {
    // Using eprintln! as a minimal fallback; consumers can override by
    // installing a `log` crate subscriber.
    #[cfg(debug_assertions)]
    eprintln!("[cencori::telemetry] {message}");
}