feat(kpihistory): classify KPI metrics gauge-vs-rate for hourly rollups (plan #22 T2)
Add KpiRollupAggregation { Gauge, Rate } enum + KpiMetricAggregationCatalog.Resolve(source, metric)
that the hourly rollup fold (T3) consults. Rate = sum-per-hour for per-interval delta counters;
Gauge = last-value-per-hour default (also the safe fallback for unknown/new metrics, never throws).
totalEventsLastHour/errorEventsLastHour classified Gauge (rolling trailing-hour counts, not
per-interval deltas) per authoritative source semantics.
Claude-Session: https://claude.ai/code/session_01MtdgwpEeCUn6cUA5f1LMPj
This commit is contained in:
Joseph Doherty
@@ -0,0 +1,125 @@
|
||||
namespace ZB.MOM.WW.ScadaBridge.Commons.Types.Kpi;
|
||||
|
||||
/// <summary>
|
||||
/// How a KPI metric must be folded when an hour of one-minute
|
||||
/// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Entities.Kpi.KpiSample"/> rows is
|
||||
/// aggregated into a single <c>KpiRollupHourly</c> row ("KPI History & Trends"
|
||||
/// hourly rollups, deferred #22). The correct fold differs by metric semantics, and
|
||||
/// choosing the wrong one silently corrupts long-range trend charts.
|
||||
/// </summary>
|
||||
public enum KpiRollupAggregation
|
||||
{
|
||||
/// <summary>
|
||||
/// An instantaneous gauge (e.g. queue depth, buffered count, oldest-pending age).
|
||||
/// The faithful hourly fold is <strong>last-value-per-hour</strong> — a gauge has
|
||||
/// no meaningful sum across the 60 one-minute samples in an hour; summing would
|
||||
/// invent a nonsensical total, whereas the latest reading is the value that a live
|
||||
/// tile would have shown at the hour boundary.
|
||||
/// </summary>
|
||||
Gauge = 0,
|
||||
|
||||
/// <summary>
|
||||
/// An already-windowed rate / delta counter (e.g. delivered-last-interval,
|
||||
/// per-interval error counts). The faithful hourly fold is
|
||||
/// <strong>sum-per-hour</strong> — each minute's sample is a fresh count of what
|
||||
/// happened in that interval, so the hour's true total is the sum of its samples.
|
||||
/// Folding a rate as last-value would keep one minute's delta and discard the other
|
||||
/// 59, silently under-counting every long-range total.
|
||||
/// </summary>
|
||||
Rate = 1,
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Authoritative classification of every KPI metric emitted by the four
|
||||
/// <see cref="ZB.MOM.WW.ScadaBridge.Commons.Interfaces.Kpi.IKpiSampleSource"/>
|
||||
/// implementations as a <see cref="KpiRollupAggregation.Gauge"/> or a
|
||||
/// <see cref="KpiRollupAggregation.Rate"/>, keyed by the <c>(source, metric)</c>
|
||||
/// pair. The hourly rollup fold consults this to pick last-value-per-hour vs.
|
||||
/// sum-per-hour for each series.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// Keying by <c>(source, metric)</c> — not metric alone — is deliberate:
|
||||
/// <c>deliveredLastInterval</c> is emitted by both
|
||||
/// <see cref="KpiSources.NotificationOutbox"/> and <see cref="KpiSources.SiteCallAudit"/>,
|
||||
/// so a metric name is not globally unique. Every metric string is taken from the
|
||||
/// emitting source verbatim (shared <see cref="KpiMetrics"/> constants where they exist,
|
||||
/// otherwise the source's own private literal), so this catalog stays a faithful mirror
|
||||
/// of what actually lands in <c>KpiSample.Metric</c>.
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// The catalog stores only the <see cref="KpiRollupAggregation.Rate"/> pairs; anything
|
||||
/// not listed — including an unknown, newly-added metric — resolves to
|
||||
/// <see cref="KpiRollupAggregation.Gauge"/>. Gauge is the safe default: last-value-per-hour
|
||||
/// never fabricates a total, so a metric that slips in without being classified degrades
|
||||
/// to a plausible reading rather than crashing the fold or silently multiplying a count.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
public static class KpiMetricAggregationCatalog
|
||||
{
|
||||
// Metric literals for the sources that keep their names private (no shared
|
||||
// KpiMetrics constant exists for these). Charted metrics use the KpiMetrics catalog.
|
||||
private const string SiteCallAuditDeliveredLastInterval = "deliveredLastInterval";
|
||||
private const string SiteHealthAlarmEvalErrors = "alarmEvalErrors";
|
||||
private const string SiteHealthEventLogWriteFailures = "eventLogWriteFailures";
|
||||
|
||||
/// <summary>
|
||||
/// The <c>(source, metric)</c> pairs classified as <see cref="KpiRollupAggregation.Rate"/>
|
||||
/// (sum-per-hour). Every other emitted metric is a <see cref="KpiRollupAggregation.Gauge"/>.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// <para>
|
||||
/// Rate members are per-interval / per-report deltas whose hour total is the sum of
|
||||
/// its minute samples:
|
||||
/// <list type="bullet">
|
||||
/// <item><c>NotificationOutbox/deliveredLastInterval</c> — rows delivered in the last KPI interval.</item>
|
||||
/// <item><c>SiteCallAudit/failedLastInterval</c> — cached calls that failed permanently in the last KPI interval.</item>
|
||||
/// <item><c>SiteCallAudit/deliveredLastInterval</c> — cached calls delivered in the last KPI interval.</item>
|
||||
/// <item><c>SiteHealth/scriptErrors</c>, <c>SiteHealth/alarmEvalErrors</c>,
|
||||
/// <c>SiteHealth/deadLetters</c>, <c>SiteHealth/eventLogWriteFailures</c> — raw error
|
||||
/// counts <em>per health-report interval</em> (site health reports carry raw counts per
|
||||
/// interval, not running totals), so they accumulate over the hour.</item>
|
||||
/// </list>
|
||||
/// </para>
|
||||
/// <para>
|
||||
/// <strong>Deliberately NOT Rate — the <c>*LastHour</c> audit metrics are Gauges.</strong>
|
||||
/// <c>AuditLog/totalEventsLastHour</c> and <c>AuditLog/errorEventsLastHour</c> read as
|
||||
/// "rate-like" by name, but <see cref="ZB.MOM.WW.ScadaBridge.AuditLog"/>'s sample source
|
||||
/// computes each as a <em>rolling trailing-one-hour</em> count (a fixed 1-hour window,
|
||||
/// re-evaluated at every capture). Each minute's value therefore already <em>is</em> the
|
||||
/// last-hour total, and consecutive minutes overlap by 59 minutes. Summing the 60 samples
|
||||
/// in an hour would count each event dozens of times (~60× over-count). The correct fold is
|
||||
/// last-value-per-hour: at the hour boundary the latest rolling-hour count closely tracks
|
||||
/// the hour's own volume, exactly like every other gauge. So both stay
|
||||
/// <see cref="KpiRollupAggregation.Gauge"/>, overriding the tentative plan list per the
|
||||
/// authoritative source semantics.
|
||||
/// </para>
|
||||
/// </remarks>
|
||||
private static readonly HashSet<(string Source, string Metric)> RatePairs = new()
|
||||
{
|
||||
(KpiSources.NotificationOutbox, KpiMetrics.NotificationOutbox.DeliveredLastInterval),
|
||||
(KpiSources.SiteCallAudit, KpiMetrics.SiteCallAudit.FailedLastInterval),
|
||||
(KpiSources.SiteCallAudit, SiteCallAuditDeliveredLastInterval),
|
||||
(KpiSources.SiteHealth, KpiMetrics.SiteHealth.ScriptErrors),
|
||||
(KpiSources.SiteHealth, SiteHealthAlarmEvalErrors),
|
||||
(KpiSources.SiteHealth, KpiMetrics.SiteHealth.DeadLetters),
|
||||
(KpiSources.SiteHealth, SiteHealthEventLogWriteFailures),
|
||||
};
|
||||
|
||||
/// <summary>
|
||||
/// Resolves how the metric identified by <paramref name="source"/> +
|
||||
/// <paramref name="metric"/> must be folded into an hourly rollup.
|
||||
/// </summary>
|
||||
/// <param name="source">The emitting KPI source (a <see cref="KpiSources"/> value).</param>
|
||||
/// <param name="metric">The metric name as persisted in <c>KpiSample.Metric</c>.</param>
|
||||
/// <returns>
|
||||
/// <see cref="KpiRollupAggregation.Rate"/> for a known per-interval counter;
|
||||
/// <see cref="KpiRollupAggregation.Gauge"/> for every known gauge <em>and</em> for any
|
||||
/// unknown / newly-added <c>(source, metric)</c> pair. Never throws — the fold must not
|
||||
/// crash on a metric added after this catalog was last updated.
|
||||
/// </returns>
|
||||
public static KpiRollupAggregation Resolve(string source, string metric) =>
|
||||
RatePairs.Contains((source, metric))
|
||||
? KpiRollupAggregation.Rate
|
||||
: KpiRollupAggregation.Gauge;
|
||||
}
|
||||
@@ -0,0 +1,151 @@
|
||||
using ZB.MOM.WW.ScadaBridge.Commons.Types.Kpi;
|
||||
|
||||
namespace ZB.MOM.WW.ScadaBridge.Commons.Tests.Kpi;
|
||||
|
||||
/// <summary>
|
||||
/// Tests for <see cref="KpiMetricAggregationCatalog"/> — the gauge-vs-rate
|
||||
/// classification the hourly rollup fold consults. Covers totality over every
|
||||
/// metric the four <c>IKpiSampleSource</c> implementations actually emit, the
|
||||
/// specific Rate set, a gauge sampling, and the unknown-metric default.
|
||||
/// </summary>
|
||||
public class KpiMetricAggregationTests
|
||||
{
|
||||
// Every (source, metric) pair emitted by the four sample sources, transcribed
|
||||
// from the source code. The catalog must classify all of them (totality).
|
||||
public static readonly (string Source, string Metric)[] AllEmittedMetrics =
|
||||
{
|
||||
// NotificationOutboxKpiSampleSource
|
||||
(KpiSources.NotificationOutbox, "queueDepth"),
|
||||
(KpiSources.NotificationOutbox, "stuckCount"),
|
||||
(KpiSources.NotificationOutbox, "parkedCount"),
|
||||
(KpiSources.NotificationOutbox, "deliveredLastInterval"),
|
||||
(KpiSources.NotificationOutbox, "oldestPendingAgeSeconds"),
|
||||
|
||||
// SiteCallAuditKpiSampleSource
|
||||
(KpiSources.SiteCallAudit, "buffered"),
|
||||
(KpiSources.SiteCallAudit, "parked"),
|
||||
(KpiSources.SiteCallAudit, "failedLastInterval"),
|
||||
(KpiSources.SiteCallAudit, "deliveredLastInterval"),
|
||||
(KpiSources.SiteCallAudit, "stuck"),
|
||||
(KpiSources.SiteCallAudit, "oldestPendingAgeSeconds"),
|
||||
|
||||
// AuditLogKpiSampleSource
|
||||
(KpiSources.AuditLog, "totalEventsLastHour"),
|
||||
(KpiSources.AuditLog, "errorEventsLastHour"),
|
||||
(KpiSources.AuditLog, "backlogTotal"),
|
||||
|
||||
// SiteHealthKpiSampleSource
|
||||
(KpiSources.SiteHealth, "connectionsUp"),
|
||||
(KpiSources.SiteHealth, "connectionsDown"),
|
||||
(KpiSources.SiteHealth, "scriptErrors"),
|
||||
(KpiSources.SiteHealth, "alarmEvalErrors"),
|
||||
(KpiSources.SiteHealth, "sfBufferDepth"),
|
||||
(KpiSources.SiteHealth, "deadLetters"),
|
||||
(KpiSources.SiteHealth, "parkedMessages"),
|
||||
(KpiSources.SiteHealth, "deployedInstances"),
|
||||
(KpiSources.SiteHealth, "enabledInstances"),
|
||||
(KpiSources.SiteHealth, "disabledInstances"),
|
||||
(KpiSources.SiteHealth, "auditBacklogPending"),
|
||||
(KpiSources.SiteHealth, "eventLogWriteFailures"),
|
||||
};
|
||||
|
||||
// The (source, metric) pairs that must fold as Rate (sum-per-hour).
|
||||
public static readonly (string Source, string Metric)[] RateMetrics =
|
||||
{
|
||||
(KpiSources.NotificationOutbox, "deliveredLastInterval"),
|
||||
(KpiSources.SiteCallAudit, "failedLastInterval"),
|
||||
(KpiSources.SiteCallAudit, "deliveredLastInterval"),
|
||||
(KpiSources.SiteHealth, "scriptErrors"),
|
||||
(KpiSources.SiteHealth, "alarmEvalErrors"),
|
||||
(KpiSources.SiteHealth, "deadLetters"),
|
||||
(KpiSources.SiteHealth, "eventLogWriteFailures"),
|
||||
};
|
||||
|
||||
// A representative sampling of gauges — including the two *LastHour audit
|
||||
// metrics that are rolling last-hour gauges, NOT rates (deliberate override).
|
||||
public static readonly (string Source, string Metric)[] GaugeSampling =
|
||||
{
|
||||
(KpiSources.NotificationOutbox, "queueDepth"),
|
||||
(KpiSources.NotificationOutbox, "oldestPendingAgeSeconds"),
|
||||
(KpiSources.SiteCallAudit, "buffered"),
|
||||
(KpiSources.SiteCallAudit, "stuck"),
|
||||
(KpiSources.AuditLog, "backlogTotal"),
|
||||
(KpiSources.AuditLog, "totalEventsLastHour"),
|
||||
(KpiSources.AuditLog, "errorEventsLastHour"),
|
||||
(KpiSources.SiteHealth, "connectionsUp"),
|
||||
(KpiSources.SiteHealth, "connectionsDown"),
|
||||
(KpiSources.SiteHealth, "sfBufferDepth"),
|
||||
(KpiSources.SiteHealth, "deployedInstances"),
|
||||
};
|
||||
|
||||
public static IEnumerable<object[]> AllEmittedCases() =>
|
||||
AllEmittedMetrics.Select(m => new object[] { m.Source, m.Metric });
|
||||
|
||||
public static IEnumerable<object[]> RateCases() =>
|
||||
RateMetrics.Select(m => new object[] { m.Source, m.Metric });
|
||||
|
||||
public static IEnumerable<object[]> GaugeCases() =>
|
||||
GaugeSampling.Select(m => new object[] { m.Source, m.Metric });
|
||||
|
||||
[Theory]
|
||||
[MemberData(nameof(AllEmittedCases))]
|
||||
public void Resolve_EveryEmittedMetric_ReturnsDefinedAggregation(string source, string metric)
|
||||
{
|
||||
var result = KpiMetricAggregationCatalog.Resolve(source, metric);
|
||||
|
||||
Assert.True(
|
||||
result is KpiRollupAggregation.Gauge or KpiRollupAggregation.Rate,
|
||||
$"({source}, {metric}) resolved to an undefined aggregation: {result}");
|
||||
}
|
||||
|
||||
[Theory]
|
||||
[MemberData(nameof(RateCases))]
|
||||
public void Resolve_RateMetrics_ClassifiedAsRate(string source, string metric)
|
||||
{
|
||||
Assert.Equal(KpiRollupAggregation.Rate, KpiMetricAggregationCatalog.Resolve(source, metric));
|
||||
}
|
||||
|
||||
[Theory]
|
||||
[MemberData(nameof(GaugeCases))]
|
||||
public void Resolve_GaugeSampling_ClassifiedAsGauge(string source, string metric)
|
||||
{
|
||||
Assert.Equal(KpiRollupAggregation.Gauge, KpiMetricAggregationCatalog.Resolve(source, metric));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Resolve_LastHourAuditMetrics_AreGaugeNotRate()
|
||||
{
|
||||
// Rolling trailing-one-hour counts: last-value-per-hour is correct; summing
|
||||
// 60 overlapping minute samples would ~60x over-count. Guard the decision.
|
||||
Assert.Equal(
|
||||
KpiRollupAggregation.Gauge,
|
||||
KpiMetricAggregationCatalog.Resolve(KpiSources.AuditLog, "totalEventsLastHour"));
|
||||
Assert.Equal(
|
||||
KpiRollupAggregation.Gauge,
|
||||
KpiMetricAggregationCatalog.Resolve(KpiSources.AuditLog, "errorEventsLastHour"));
|
||||
}
|
||||
|
||||
[Theory]
|
||||
[InlineData(KpiSources.NotificationOutbox, "someBrandNewMetricAddedLater")]
|
||||
[InlineData("AnEntirelyNewSource", "anyMetric")]
|
||||
[InlineData(KpiSources.SiteHealth, "")]
|
||||
public void Resolve_UnknownMetric_DefaultsToGauge(string source, string metric)
|
||||
{
|
||||
// The fold must never crash on a metric added after this catalog was updated;
|
||||
// Gauge (last-value) is the safe, non-fabricating default.
|
||||
Assert.Equal(KpiRollupAggregation.Gauge, KpiMetricAggregationCatalog.Resolve(source, metric));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Resolve_SameMetricNameDifferentSource_KeysOnSourcePair()
|
||||
{
|
||||
// deliveredLastInterval is Rate under both sources here, but the point is the
|
||||
// API keys on (source, metric) rather than metric alone — both resolve.
|
||||
Assert.Equal(
|
||||
KpiRollupAggregation.Rate,
|
||||
KpiMetricAggregationCatalog.Resolve(KpiSources.NotificationOutbox, "deliveredLastInterval"));
|
||||
Assert.Equal(
|
||||
KpiRollupAggregation.Rate,
|
||||
KpiMetricAggregationCatalog.Resolve(KpiSources.SiteCallAudit, "deliveredLastInterval"));
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user