TelemetrySummary.cs

namespace Gondwana.Diagnostics;

public enum TelemetryMetricKind
{
    Sample,
    Gauge,
    LifetimeCounter
}

public enum TelemetryAvailability
{
    Unsupported,
    NotApplicable,
    NotYetSampled,
    Available
}

public sealed record TelemetrySummary(
    TelemetryAvailability Availability, long Count, double Sum,
    double? Minimum, double? Maximum, double? Last)
{
    public TelemetryMetricKind Kind { get; init; }
    public double? WindowDelta { get; init; }
    public double? LastObservedSeconds { get; init; }
    public double? Mean => Count == 0 ? null : Sum / Count;

    public static TelemetrySummary Combine(IEnumerable<TelemetrySummary> summaries)
    {
        ArgumentNullException.ThrowIfNull(summaries);
        long count = 0;
        double sum = 0;
        double? min = null, max = null, last = null;
        double? observed = null, delta = null;
        TelemetryMetricKind? kind = null;
        var availability = TelemetryAvailability.Unsupported;
        foreach (var value in summaries)
        {
            if (kind is not null && kind != value.Kind) throw new ArgumentException("Cannot combine different metric kinds.", nameof(summaries));
            kind = value.Kind;
            if (value.Availability > availability) availability = value.Availability;
            if (value.Count == 0) continue;
            count += value.Count;
            sum += value.Sum;
            min = min is null ? value.Minimum : Math.Min(min.Value, value.Minimum!.Value);
            max = max is null ? value.Maximum : Math.Max(max.Value, value.Maximum!.Value);
            last = value.Last;
            observed = value.LastObservedSeconds;
            if (value.WindowDelta is { } change) delta = (delta ?? 0) + change;
        }
        return new(availability, count, sum, min, max, last)
        {
            Kind = kind ?? TelemetryMetricKind.Sample,
            LastObservedSeconds = observed,
            WindowDelta = delta
        };
    }
}

public sealed record TelemetryOptions
{
    internal const long MaxRetainedMetricSummaries = 1_048_576;

    internal const long MaxPublishedMetricSummariesPerSecond = 262_144;

    public TimeSpan Interval { get; init; } = TimeSpan.FromMilliseconds(250);
    public int HistoryCapacity { get; init; } = 120;
    public int SourceCapacity { get; init; } = 16;
    public int MetricCapacity { get; init; } = 128;

    internal void Validate()
    {
        if (Interval < TimeSpan.FromMilliseconds(10) || Interval > TimeSpan.FromMinutes(1))
            throw new ArgumentOutOfRangeException(nameof(Interval));
        if (HistoryCapacity is < 1 or > 1024) throw new ArgumentOutOfRangeException(nameof(HistoryCapacity));
        if (SourceCapacity is < 1 or > 64) throw new ArgumentOutOfRangeException(nameof(SourceCapacity));
        if (MetricCapacity is < 8 or > 512) throw new ArgumentOutOfRangeException(nameof(MetricCapacity));
 
        long retainedMetricSummaries =
            (long)HistoryCapacity * SourceCapacity * MetricCapacity;
        if (retainedMetricSummaries > MaxRetainedMetricSummaries)
        {
            throw new ArgumentException(
                $"HistoryCapacity * SourceCapacity * MetricCapacity must not exceed {MaxRetainedMetricSummaries:N0} retained metric summaries.");
        }
 
        double publishedMetricSummariesPerSecond =
            (double)SourceCapacity * MetricCapacity / Interval.TotalSeconds;
        if (publishedMetricSummariesPerSecond > MaxPublishedMetricSummariesPerSecond)
        {
            throw new ArgumentException(
                $"SourceCapacity * MetricCapacity / Interval.TotalSeconds must not exceed {MaxPublishedMetricSummariesPerSecond:N0} configured metric summaries per second.");
        }
    }
}

public sealed record TelemetrySnapshot(long Generation, double StartedSeconds, double EndedSeconds,
    IReadOnlyList<TelemetrySourceSnapshot> Sources, bool Truncated)
{
    public double ElapsedSeconds => EndedSeconds - StartedSeconds;
}

public sealed record TelemetrySourceSnapshot(long Id, string Name, string Backend,
    IReadOnlyDictionary<string, TelemetrySummary> Metrics);