perf(sitelog): sampled per-run events; interval run summaries; site_events replication policy pinned

Implements WP3.2 stage (b) per docs/plans/2026-08-15-site-events-policy-design.md. - Per-run instance-script Started/Completed Info site events are now off by default (SiteRuntimeOptions.PerRunScriptEvents=false) instead of firing on every run, closing the dominant site_events writer. Gated at the ScriptRunLauncher call sites (moved there from ScriptExecutionActor by WP3.1). Error-level events (timeout/failure/stuck-watchdog/recursion-limit) remain unconditional. - ScriptRunSummaryRecorder accumulates per-(instance, script) run counters and a new site-only ScriptRunSummaryFlushService emits one aggregate "script" Info site event per ScriptRunSummaryIntervalSeconds (default 300s), top-50-script breakdown with an "others" rollup, zero-activity intervals emit nothing. - Per-script opt-in via PerRunScriptEventScripts ("Instance/Script" exact or "Instance/*" wildcard), matched by the new pure ScriptRunEventPolicy. All three options are read from IOptionsMonitor<SiteRuntimeOptions> per run, so the policy is hot-togglable without a restart. - Fixed the stale "event log is not replicated" comment at AkkaHostedService.cs (~905): site_events IS registered in SiteLocalDbSetup.ReplicatedTables — the singleton is what makes queries always hit the actively-written copy; replication is what gives the singleton history to read after a failover (memo Decision (b)). site_events replication itself is unchanged (still registered) and already pinned by tests/ZB.MOM.WW.ScadaBridge.Host.Tests/SiteLocalDbCdcRegistrationTests.cs. - Updated Component-SiteEventLogging.md (Volume Policy section, corrected Storage/replication rationale) and Component-SiteRuntime.md (Script Run Launch + Error Handling sections).
2026-08-14 22:56:08 -04:00
parent 799fd041ec
commit c254d0740e
15 changed files with 922 additions and 27 deletions
@@ -0,0 +1,55 @@
+namespace ZB.MOM.WW.ScadaBridge.SiteRuntime.Scripts;
+
+/// <summary>
+/// WP3.2 (site_events volume policy — docs/plans/2026-08-15-site-events-policy-design.md):
+/// decides whether an instance script run should emit the legacy per-run Started/Completed
+/// Info site events, or stay silent and let <see cref="ScriptRunSummaryRecorder"/>'s interval
+/// aggregate carry the signal instead. Pure and side-effect-free — no DI, no actor context —
+/// so the three opt-in shapes (global switch, exact per-script match, per-instance wildcard)
+/// are unit-testable in isolation and reusable from <see cref="ScriptRunLauncher"/> without
+/// dragging config plumbing into the run body.
+/// </summary>
+public static class ScriptRunEventPolicy
+{
+    /// <summary>
+    /// True when per-run Started/Completed Info events should be emitted for this run.
+    /// </summary>
+    /// <param name="options">
+    /// The effective <see cref="SiteRuntimeOptions"/> snapshot for this run (the caller reads
+    /// <c>IOptionsMonitor&lt;SiteRuntimeOptions&gt;.CurrentValue</c> per run so this stays
+    /// hot-togglable — see <see cref="SiteRuntimeOptions.PerRunScriptEvents"/>).
+    /// </param>
+    /// <param name="instanceName">The owning instance's name.</param>
+    /// <param name="scriptName">The script's name.</param>
+    /// <returns>
+    /// <c>true</c> if <see cref="SiteRuntimeOptions.PerRunScriptEvents"/> is set, or if
+    /// <see cref="SiteRuntimeOptions.PerRunScriptEventScripts"/> contains an exact
+    /// <c>"{instanceName}/{scriptName}"</c> entry or an <c>"{instanceName}/*"</c> wildcard
+    /// entry for this instance; otherwise <c>false</c>.
+    /// </returns>
+    public static bool ShouldEmitPerRun(SiteRuntimeOptions options, string instanceName, string scriptName)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+
+        if (options.PerRunScriptEvents)
+            return true;
+
+        var scripts = options.PerRunScriptEventScripts;
+        if (scripts is not { Count: > 0 })
+            return false;
+
+        var exact = $"{instanceName}/{scriptName}";
+        var wildcard = $"{instanceName}/*";
+
+        foreach (var entry in scripts)
+        {
+            if (string.Equals(entry, exact, StringComparison.Ordinal) ||
+                string.Equals(entry, wildcard, StringComparison.Ordinal))
+            {
+                return true;
+            }
+        }
+
+        return false;
+    }
+}