From 2609c5462e8ec36ae76ca905a28a13c229b9b0e6 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Tue, 13 Oct 2026 01:17:51 -0400 Subject: [PATCH] =?UTF-8?q?fix(historian):=20#693=20re-review=20=E2=80=94?= =?UTF-8?q?=20AtTime=20read=20cap=2064=20+=2016=20per=20time=20(bursty=20t?= =?UTF-8?q?ags=20need=20~6)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A time inside a gap of a bursty tag costs a 64-row jump read landing in the next burst plus a bisection back across the gap (~6 reads), so the 64 + 4/time cap refused a 1 h/day 1 Hz tag asked at noon on 30/100/300 consecutive days (186/606/1,806 reads) that AVEVA's own AtTime served. The cap is a runaway guard (HistoryReadDeadline bounds wall clock): now 64 + 16 per distinct time. Regression tests for x30/x100/x300 (each <= 7 reads a time, values checked). Docs: DateTime-hinted nodes are stepped but keep the gateway's Double (the Gateway never historizes DateTime nodes; the SQL backends return DateTime). --- docs/Historian.md | 12 ++- .../GatewayAtTimeReader.cs | 10 ++- .../GatewayAtTimeTests.cs | 79 ++++++++++++++++++- 3 files changed, 93 insertions(+), 8 deletions(-) diff --git a/docs/Historian.md b/docs/Historian.md index b44c88d8..8aabfeb2 100644 --- a/docs/Historian.md +++ b/docs/Historian.md @@ -794,8 +794,11 @@ data. a 10-minute gap 6 reads (< 10k rows). (Before the review fix a full segment reset the width and a full whole-remainder read was discarded, so a dense tag that stopped weeks ago gave up after 65 reads.) More than 1,024 stored samples within one millisecond fail the node `BadTooManyOperations` (not counted as a backend failure). -- **Bounded.** One request takes at most **64 + 4 × distinct times** raw reads; past it the node fails `BadTooManyOperations` - ("needed more than N raw reads", naming a small strict-gateway ceiling when one bounded the reads). A strict gateway whose ceiling is +- **Bounded.** One request takes at most **64 + 16 × distinct times** raw reads; past it the node fails `BadTooManyOperations` + ("needed more than N raw reads", naming a small strict-gateway ceiling when one bounded the reads). It is a runaway guard, not a + budget (`HistoryReadDeadline` bounds the wall clock): a time inside a gap of a bursty tag legitimately costs a jump read plus a + bisection back across the gap, ≈ 6 reads — a 1 h/day 1 Hz tag asked at noon on 30 / 100 / 300 consecutive days takes 186 / 606 / + 1,806 reads, which the first cut's 64 + 4 per time refused although AVEVA's own AtTime served it. A strict gateway whose ceiling is below 4 rows is refused up front with a message naming the ceiling; a small one (e.g. 10) is served by paging within the cap. - **Wire shape.** Every request bound is a whole millisecond and a row counts only **strictly inside** its request, so AVEVA's synthetic boundary row at the query start (#687) — and any row at the query end — is never taken for a stored sample. A Bad row is value-less @@ -809,7 +812,10 @@ data. **before** the shared evaluator runs, so its own type rules apply exactly as on the SQL backends: a **Boolean** node (value ≠ 0) is **stepped** — never 0.5; an **integer** node is interpolated, rounded half away from zero and returned as the node's own integer type (`Int32` ⇒ `int`); Float / Double interpolate as Double (as the SQL backends return them). With no - hint (an unknown node) every numeric tag interpolates as Double. A **DateTime** node is stepped. Under an integer hint a NaN, ±∞ or + hint (an unknown node) every numeric tag interpolates as Double. A **DateTime** node is stepped, but its value stays the + gateway's Double: the Gateway never historizes a DateTime node (`HistorianTypeMapper` skips it at provisioning and the recorder drops + non-numeric values), so such a node only has history if something else wrote that AVEVA tag, and the numeric encoding is not known + here — the SQL backends store DateTime as its own kind and return a `DateTime`. Under an integer hint a NaN, ±∞ or out-of-Int64-range stored value is no integer: it is treated as unusable (as `BadNoData`), so a neighbour like that is never interpolated or saturated into a Good value. - **What differs between backends (by design, not changed by #693).** Only the **Gateway** converts an AtTime result to the node's diff --git a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Gateway/GatewayAtTimeReader.cs b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Gateway/GatewayAtTimeReader.cs index f42ede4d..f6d9f107 100644 --- a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Gateway/GatewayAtTimeReader.cs +++ b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Gateway/GatewayAtTimeReader.cs @@ -41,7 +41,7 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.Historian.Gateway; /// 2 ms the segment is the whole stretch from the known row (never a 100 ns step). /// /// -/// Bounded. One request may take at most 64 + 4 × distinct times raw reads (, +/// Bounded. One request may take at most 64 + 16 × distinct times raw reads (, /// ); past it — or with a strict-gateway ceiling below rows — the /// node fails BadTooManyOperations with a message naming the limit. A jump read (to a time far past the previous /// read) asks for only rows, so a thousand times spread over ten years cost about a thousand @@ -82,8 +82,12 @@ internal static class GatewayAtTimeReader /// Raw reads one request may always take … internal const int BaseReads = 64; - /// … plus this many per distinct requested time. - internal const int ReadsPerTime = 4; + /// + /// … plus this many per distinct requested time. A runaway guard, not a budget (HistoryReadDeadline bounds the + /// wall clock): a time inside a gap of a bursty tag legitimately costs a jump read plus a bisection back across the gap + /// (≈ 6 reads — a 1 h/day tag asked at noon on consecutive days), so 4 refused requests AVEVA's own AtTime served. + /// + internal const int ReadsPerTime = 16; /// The first walk-back segment's width when the window read showed no density. internal static readonly TimeSpan InitialWalkWidth = TimeSpan.FromMinutes(1); diff --git a/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Gateway.Tests/GatewayAtTimeTests.cs b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Gateway.Tests/GatewayAtTimeTests.cs index 3c48537a..11e47fa2 100644 --- a/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Gateway.Tests/GatewayAtTimeTests.cs +++ b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.Historian.Gateway.Tests/GatewayAtTimeTests.cs @@ -575,6 +575,81 @@ public sealed class GatewayAtTimeTests ex.Message.ShouldContain("row ceiling (2"); } + /// A bursty tag: 1 Hz for the first hour of every day (value = seconds since ). + private sealed class BurstStore(DateTime from, int days) + { + public long RowsStreamed; + private const long Burst = 3600 * TimeSpan.TicksPerSecond; + + private DateTime? FirstAtOrAfter(DateTime t) + { + if (t <= from) return from; + var d = (t - from).Ticks / TimeSpan.TicksPerDay; + var inDay = (t - from).Ticks % TimeSpan.TicksPerDay; + var r = inDay >= Burst + ? from.AddDays(d + 1) + : from.AddTicks(d * TimeSpan.TicksPerDay + (inDay + TimeSpan.TicksPerSecond - 1) / TimeSpan.TicksPerSecond * TimeSpan.TicksPerSecond); + if ((r - from).Ticks % TimeSpan.TicksPerDay >= Burst) r = from.AddDays(d + 1); + return r < from.AddDays(days) ? r : null; + } + + private DateTime? LastBefore(DateTime t) + { + if (t <= from) return null; + var x = (t - from).Ticks - 1; + var d = x / TimeSpan.TicksPerDay; + var inDay = x % TimeSpan.TicksPerDay; + var r = inDay >= Burst - TimeSpan.TicksPerSecond + ? from.AddTicks(d * TimeSpan.TicksPerDay + Burst - TimeSpan.TicksPerSecond) + : from.AddTicks(d * TimeSpan.TicksPerDay + inDay / TimeSpan.TicksPerSecond * TimeSpan.TicksPerSecond); + var last = from.AddDays(days - 1).AddTicks(Burst - TimeSpan.TicksPerSecond); + return r > last ? last : r; + } + + private HistorianSample Row(DateTime t, uint quality = 0, DateTime? at = null) => new() + { + Tag = "T", Timestamp = Timestamp.FromDateTime(at ?? t), NumericValue = (t - from).Ticks / TimeSpan.TicksPerSecond, + OpcQuality = 192, Quality = quality, + }; + + public FakeHistorianGatewayClient Client() => new() { RawSource = Serve }; + + private IEnumerable Serve(DateTime start, DateTime end, int max) + { + if (max <= 0 || end < start || end > Now.AddDays(2) + || start.Ticks % TimeSpan.TicksPerMillisecond != 0 || end.Ticks % TimeSpan.TicksPerMillisecond != 0) + throw new Grpc.Core.RpcException(new Grpc.Core.Status(Grpc.Core.StatusCode.InvalidArgument, "refused")); + var rows = new List(); + if (FirstAtOrAfter(start) != start) + rows.Add(LastBefore(start) is { } p + ? Row(p, 133, start) + : new HistorianSample { Tag = "T", Timestamp = Timestamp.FromDateTime(start), OpcQuality = 0, Quality = 1 }); + for (var t = FirstAtOrAfter(start); t is { } u && u <= end && rows.Count < max; t = FirstAtOrAfter(u.AddTicks(1))) + rows.Add(Row(u)); + RowsStreamed += rows.Count; + return rows; + } + } + + [Theory] // re-review: every time in a gap of a bursty tag costs a jump read + a bisection — the cap must allow that + [InlineData(30)] + [InlineData(100)] + [InlineData(300)] + public async Task A_bursty_tag_asked_at_noon_on_consecutive_days_is_served(int days) + { + var from = Now.Date.AddDays(-days - 1); + var fake = new BurstStore(from, days + 1).Client(); + var times = Enumerable.Range(0, days).Select(d => from.AddDays(d).AddHours(12)).ToArray(); + var s = await AtTime(fake, times); + for (var d = 0; d < days; d++) + { + double prev = d * 86400 + 3599, next = (d + 1) * 86400; + ((double)s[d].Value!).ShouldBe(prev + (next - prev) * (12 * 3600 - 3599.0) / (86400 - 3599.0), 1e-6); + s[d].StatusCode.ShouldBe(GoodInterpolated); + } + fake.ReadRawCallCount.ShouldBeLessThanOrEqualTo(7 * days); // ≈ 6 a time; the cap is 64 + 16 a time + } + [Fact] // L1: a small ceiling is served (paging), within the read cap public async Task A_small_ceiling_is_served_within_the_read_cap() { @@ -596,10 +671,10 @@ public sealed class GatewayAtTimeTests fake.RawStreamsCompleted.ShouldBe(3); } - [Fact] // the default cap scales with the request: 64 + 4 per distinct time + [Fact] // the default cap scales with the request: 64 + 16 per distinct time (a runaway guard; a bursty tag needs ≈ 6) public async Task The_default_read_cap_is_64_plus_4_per_distinct_time() { - (GatewayAtTimeReader.BaseReads, GatewayAtTimeReader.ReadsPerTime).ShouldBe((64, 4)); + (GatewayAtTimeReader.BaseReads, GatewayAtTimeReader.ReadsPerTime).ShouldBe((64, 16)); await Task.CompletedTask; }