TimeQuality.Core

A lightweight, dependency-free .NET library for evaluating time synchronization quality.

Overview

TimeQuality.Core answers one specific question: "Given a stream of time offset measurements, is my time synchronization stable and good enough - right now?"

The library ingests timestamped offset samples, computes drift, jitter, and key statistics, then emits a deterministic health snapshot suitable for monitoring, testing, and analysis.

Design Principles

• Small surface area, high impact
• Pure math only (no IO, no charts, no exporters)
• Deterministic outputs for the same inputs
• Test-first friendly
• Zero external dependencies

Installation

dotnet add package TimeQuality.Core

Quick Start

using TimeQuality.Core;

// Configure policy and windowing
var policy = TimeQualityPolicy.Default();
var window = WindowConfig.CountBased(300);
var analyzer = new TimeQualityAnalyzer(policy, window);

// Add samples as they arrive
analyzer.AddSample(new TimeSample(
    Timestamp: DateTimeOffset.UtcNow,
    OffsetNs: 1500,
    DelayNs: 250
));

// Get current health snapshot
var snapshot = analyzer.GetSnapshot();
Console.WriteLine($"State: {snapshot.State}");
Console.WriteLine($"Mean Offset: {snapshot.MeanOffsetNs} ns");
Console.WriteLine($"Drift: {snapshot.DriftNsPerSec} ns/s");

Core Concepts

TimeSample: A single time offset measurement with timestamp, offset (ns), and optional delay (ns).

Windowing: Supports count-based (keep last N samples) or time-based (keep samples within duration) windows.

Metrics: Computes mean offset, p95/p99 percentiles, max offset, jitter (successive differences), and drift (linear regression slope).

Health Policy: Evaluates metrics against thresholds to classify synchronization as Good, Warning, or Bad.

Units

All time values use nanoseconds (ns) for offsets and delays. Drift is expressed in ns/s (nanoseconds per second).

Documentation

See DEEPDIVE.md for detailed documentation on metrics, windowing behavior, and health evaluation.

License

MIT License - see LICENSE for details.

Tags

timing ptp white-rabbit ntp synchronization metrics drift jitter