Crate mockforge_analytics 

MockForge Analytics

Provides comprehensive traffic analytics and metrics dashboard capabilities for MockForge, including:

• Time-series metrics aggregation (minute/hour/day granularity)
• Endpoint performance tracking
• Error analysis and monitoring
• Client analytics
• Traffic pattern detection
• Data export (CSV, JSON)
• Configurable retention policies

Architecture

The analytics system consists of several components:

• Database: SQLite-based storage for aggregated metrics
• Aggregator: Background service that queries Prometheus and stores metrics
• Queries: High-level query API for dashboard data
• Export: Data export functionality
• Retention: Automatic cleanup of old data

Example

use mockforge_analytics::{AnalyticsDatabase, AnalyticsConfig, RetentionConfig};
use std::path::PathBuf;

let config = AnalyticsConfig {
    enabled: true,
    database_path: PathBuf::from("analytics.db"),
    aggregation_interval_seconds: 60,
    rollup_interval_hours: 1,
    retention: RetentionConfig::default(),
    batch_size: 1000,
    max_query_results: 10000,
};

let db = AnalyticsDatabase::new(&config.database_path).await?;
db.run_migrations().await?;

// Query top endpoints
let endpoints = db.get_top_endpoints(10, None).await?;
for endpoint in &endpoints {
    println!("Endpoint: {} - {} requests", endpoint.endpoint, endpoint.total_requests);
}

Re-exports

pub use config::AnalyticsConfig;

pub use config::RetentionConfig;

pub use database::AnalyticsDatabase;

pub use error::AnalyticsError;

pub use error::Result;

pub use models::DriftPercentageMetrics;

pub use models::EndpointCoverage;

pub use models::PersonaCIHit;

pub use models::RealityLevelStaleness;

pub use models::ScenarioUsageMetrics;

pub use models::*;

pub use pillar_usage::*;

Modules

aggregator

Metrics aggregation service

config

Configuration types for the analytics system

database

Database layer for analytics storage

error

Error types for the analytics module

export

Data export functionality

models

Data models for analytics

pillar_usage

Pillar usage tracking

queries

High-level query API for analytics data

retention

Data retention and cleanup service

Functions

get_global_db

Return the global analytics database if one has been installed.

init

Initialize the analytics system with the given configuration

record_drift_percentage_async

Spawn a fire-and-forget task that records a drift percentage sample to the global analytics database. No-op when the global isn’t installed. Errors are logged at WARN — the hot path must never wait or fail because analytics is unavailable.

record_endpoint_coverage_async

Spawn a fire-and-forget task that records a single endpoint hit for coverage tracking. The HTTP middleware calls this on every matched request when analytics is installed.

record_reality_level_staleness_async

Spawn a fire-and-forget task that records the current reality level for staleness tracking. current_reality_level is the level name (e.g. "production_chaos"); staleness_days is “how long ago this level was last refreshed” — pass Some(0) when the level was set right now.

record_scenario_usage_async

Spawn a fire-and-forget task that records that a scenario fired. No-op when the global isn’t installed.

set_global_db

Install the global analytics database. Called once from the CLI / server startup when analytics is enabled. Returns Err(_) if it has already been initialised — callers should treat that as a no-op (the first installation wins).