ddn.util.monaco.history

Historical Data and Time Series

This module provides built-in time-series data collection for trend analysis.

Features:

  • Efficient time-series storage
  • Windowed aggregations (min/max/avg)
  • Statistical functions
  • Trend detection
  • Automatic collection mode
  • Memory-bounded (configurable retention)

Platform Availability:

  • Fully cross-platform (pure D implementation)
  • Linux, Windows, macOS, BSD

Copyright

Copyright (c) 2024 DDN

License

BSD-3-Clause

Authors

DDN
enum Trend
struct MetricEntry
class AutoCollector MetricCollector
fn detectTrend

Types 4

structMetricEntry(T)

Time-stamped metric entry.

Stores a single metric value with its timestamp.

Parameters

TThe type of the metric value.
Fields
SysTime timestamp
T value
enumTrend

Trend direction for time-series data.

INCREASINGValues are increasing over time
DECREASINGValues are decreasing over time
STABLEValues are relatively stable
VOLATILEValues show high volatility
classMetricCollector(T)

Time-series data collector with efficient storage and statistical analysis.

This class collects time-stamped metric values and provides windowed aggregations and statistical functions for trend analysis.

Parameters

TThe type of the metric value (e.g., double, ulong). Example: 
auto cpuHistory = new MetricCollector!double(5.minutes);
cpuHistory.record(45.2);
cpuHistory.record(52.8);

double avg = cpuHistory.average(1.minute);
Trend t = detectTrend(cpuHistory, 30.seconds);
Fields
private MetricEntry!T[] data
private Mutex mutex
private Duration maxAge
private size_t maxSize
Methods
void record(T value, SysTime timestamp = Clock.currTime())Records a metric value with an optional timestamp.
T latest()Gets the most recently recorded value.
T[] values(Duration window)Gets all values within a time window.
T min(Duration window)Gets the minimum value within a time window.
T max(Duration window)Gets the maximum value within a time window.
T average(Duration window)Gets the average value within a time window.
double stddev(Duration window)Calculates the standard deviation within a time window.
T percentile(Duration window, double p)Gets the percentile value within a time window.
size_t length()Returns the number of data points currently stored.
void clear()Clears all stored data.
void setMaxAge(Duration age)Sets the maximum age for data retention.
private void pruneOldData()Removes entries older than the retention period.
Constructors
this(Duration maxAge = dur!"hours"(1), size_t maxSize = 10000)Creates a new MetricCollector with optional retention settings.
classAutoCollector

Automatic metric collection manager.

This class starts a background thread that periodically collects various system metrics and stores them in MetricCollector instances.

Example: 

auto autoCollector = new AutoCollector(2.seconds);
autoCollector.start();

// Let it collect for a while
Thread.sleep(10.seconds);

// Get collected data
auto cpuCollector = autoCollector.cpu();
double avgCpu = cpuCollector.average(5.seconds);

autoCollector.stop();

Fields
private MetricCollector!double cpuCollector
private MetricCollector!ulong memoryCollector
private Duration interval
private Thread worker
private Mutex mutex
private Condition condition
private bool running
Methods
void start()Starts automatic metric collection.
void stop()Stops automatic metric collection.
MetricCollector!double cpu()Gets the CPU metric collector.
MetricCollector!ulong memory()Gets the memory metric collector.
void setMaxAge(Duration maxAge)Sets the retention duration for all collectors.
void clear()Clears all collected data.
private void workerFunc()Background worker function for collecting metrics.
Constructors
this(Duration interval = dur!"seconds"(1))Creates a new AutoCollector with the specified collection interval.
Destructors
~thisCleanup on destruction.

Functions 1

fnTrend detectTrend(T)(MetricCollector!T collector, Duration window)Detects the trend in a metric collector over a time window.