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; }