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