dohertj2/ScadaBridge
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

feat(siteeventlog): emit alarm-category events on alarm transitions (M1.5)

Browse Source 
AlarmActor (computed) and NativeAlarmActor (native mirror) now fire-and-forget
an 'alarm' site operational event on every state transition:
- raise/activate: Error (priority/severity >= 700) or Warning
- clear/return-to-normal, ack, inter-band transition: Info

Both actors take a new optional IServiceProvider? ctor param (default null so
existing direct-construction tests still compile); InstanceActor passes its
_serviceProvider at the two Props.Create sites. Resolution is optional and the
LogEventAsync call is fire-and-forget, so a logging failure never affects alarm
evaluation. Rehydration replays are not re-logged.

Adds a capturing FakeSiteEventLogger test helper + SingleServiceProvider.
This commit is contained in:
Joseph Doherty
2026-06-15 12:23:04 -04:00
parent f49ac51771
commit a00e43c4f9
6 changed files with 368 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/ZB.MOM.WW.ScadaBridge.SiteRuntime/Actors/AlarmActor.cs
+61 -1
View File
@@ -1,10 +1,12 @@
using Akka.Actor;
using Microsoft.CodeAnalysis.Scripting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using ZB.MOM.WW.ScadaBridge.Commons.Messages.Streaming;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Enums;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Flattening;
using ZB.MOM.WW.ScadaBridge.HealthMonitoring;
using ZB.MOM.WW.ScadaBridge.SiteEventLogging;
using ZB.MOM.WW.ScadaBridge.SiteRuntime.Scripts;
using System.Globalization;
using System.Text.Json;
@@ -37,6 +39,14 @@ public class AlarmActor : ReceiveActor
private readonly SiteRuntimeOptions _options;
private readonly ILogger _logger;
private readonly ISiteHealthCollector? _healthCollector;
private readonly IServiceProvider? _serviceProvider;
/// <summary>
/// M1.5: priority at or above which a computed-alarm raise is logged as
/// <c>Error</c> to the site event log; below it, raises log as <c>Warning</c>.
/// Mirrors the 0–1000 alarm-severity scale.
/// </summary>
private const int ErrorPriorityThreshold = 700;
private AlarmState _currentState = AlarmState.Normal;
/// <summary>
@@ -83,6 +93,9 @@ public class AlarmActor : ReceiveActor
/// <param name="compiledTriggerExpression">Pre-compiled trigger expression, or <c>null</c> for non-expression triggers.</param>
/// <param name="initialAttributes">Seed attribute snapshot so static attributes evaluate correctly at startup.</param>
/// <param name="healthCollector">Optional health collector for surfacing alarm execution metrics.</param>
/// <param name="serviceProvider">Optional DI service provider used to resolve the optional
/// <see cref="ISiteEventLogger"/> for M1.5 <c>alarm</c> operational events. Fire-and-forget;
/// a logging failure never affects alarm evaluation.</param>
public AlarmActor(
string alarmName,
string instanceName,
@@ -94,7 +107,8 @@ public class AlarmActor : ReceiveActor
ILogger logger,
Script<object?>? compiledTriggerExpression = null,
IReadOnlyDictionary<string, object?>? initialAttributes = null,
ISiteHealthCollector? healthCollector = null)
ISiteHealthCollector? healthCollector = null,
IServiceProvider? serviceProvider = null)
{
_alarmName = alarmName;
_instanceName = instanceName;
@@ -103,6 +117,7 @@ public class AlarmActor : ReceiveActor
_options = options;
_logger = logger;
_healthCollector = healthCollector;
_serviceProvider = serviceProvider;
_priority = alarmConfig.PriorityLevel;
_onTriggerScriptName = alarmConfig.OnTriggerScriptCanonicalName;
_onTriggerCompiledScript = onTriggerCompiledScript;
@@ -208,6 +223,9 @@ public class AlarmActor : ReceiveActor
_instanceName, _alarmName, AlarmState.Active, _priority, DateTimeOffset.UtcNow);
_instanceActor.Tell(alarmChanged);
// M1.5: operational `alarm` event — raise. Severity by priority.
LogAlarmEvent(RaiseSeverity(_priority), $"Alarm {_alarmName} activated (priority {_priority})");
// Spawn AlarmExecutionActor if on-trigger script defined
if (_onTriggerCompiledScript != null)
{
@@ -225,6 +243,9 @@ public class AlarmActor : ReceiveActor
var alarmChanged = new AlarmStateChanged(
_instanceName, _alarmName, AlarmState.Normal, _priority, DateTimeOffset.UtcNow);
_instanceActor.Tell(alarmChanged);
// M1.5: operational `alarm` event — return to normal.
LogAlarmEvent("Info", $"Alarm {_alarmName} cleared");
}
}
catch (Exception ex)
@@ -265,6 +286,24 @@ public class AlarmActor : ReceiveActor
};
_instanceActor.Tell(alarmChanged);
// M1.5: operational `alarm` event. Entering a band from Normal is a raise
// (severity by the band's priority); returning to None is a clear; a
// level-to-level escalation/de-escalation is an informational transition.
if (newLevel == AlarmLevel.None)
{
LogAlarmEvent("Info", $"Alarm {_alarmName} cleared ({previousLevel} → Normal)");
}
else if (previousLevel == AlarmLevel.None)
{
LogAlarmEvent(RaiseSeverity(priority),
$"Alarm {_alarmName} activated at {newLevel} (priority {priority})");
}
else
{
LogAlarmEvent("Info",
$"Alarm {_alarmName} transitioned {previousLevel} → {newLevel} (priority {priority})");
}
if (previousLevel == AlarmLevel.None
&& newLevel != AlarmLevel.None
&& _onTriggerCompiledScript != null)
@@ -273,6 +312,27 @@ public class AlarmActor : ReceiveActor
}
}
/// <summary>
/// M1.5: maps an alarm priority (0–1000) to a site-event severity for a
/// <i>raise</i> transition — <c>Error</c> at or above
/// <see cref="ErrorPriorityThreshold"/>, otherwise <c>Warning</c>. Clears and
/// inter-band transitions always log as <c>Info</c>.
/// </summary>
private static string RaiseSeverity(int priority) =>
priority >= ErrorPriorityThreshold ? "Error" : "Warning";
/// <summary>
/// M1.5: fire-and-forget an <c>alarm</c> operational event to the optional
/// <see cref="ISiteEventLogger"/>. Resolved optionally and never awaited so a
/// logging failure cannot affect alarm evaluation (matching the established
/// ScriptActor/ScriptExecutionActor pattern).
/// </summary>
private void LogAlarmEvent(string severity, string message)
{
_ = _serviceProvider?.GetService<ISiteEventLogger>()?.LogEventAsync(
"alarm", severity, _instanceName, $"AlarmActor:{_alarmName}", message);
}
/// <summary>
/// Returns the per-setpoint priority for the given level. Falls back to
/// the alarm-level <see cref="_priority"/> when the HiLo config did not
src/ZB.MOM.WW.ScadaBridge.SiteRuntime/Actors/InstanceActor.cs
+4 -2
View File
@@ -763,7 +763,8 @@ public class InstanceActor : ReceiveActor
_logger,
triggerExpression,
attributeSnapshot,
_healthCollector));
_healthCollector,
_serviceProvider));
var actorRef = Context.ActorOf(props, $"alarm-{alarm.CanonicalName}");
_alarmActors[alarm.CanonicalName] = actorRef;
@@ -793,7 +794,8 @@ public class InstanceActor : ReceiveActor
_storage,
_options,
_logger,
nativeKind));
nativeKind,
_serviceProvider));
var actorRef = Context.ActorOf(props, $"native-alarm-{nativeSource.CanonicalName}");
_nativeAlarmActors[nativeSource.CanonicalName] = actorRef;
src/ZB.MOM.WW.ScadaBridge.SiteRuntime/Actors/NativeAlarmActor.cs
+73 -4
View File
@@ -1,11 +1,13 @@
using System.Text.Json;
using Akka.Actor;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using ZB.MOM.WW.ScadaBridge.Commons.Messages.DataConnection;
using ZB.MOM.WW.ScadaBridge.Commons.Messages.Streaming;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Alarms;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Enums;
using ZB.MOM.WW.ScadaBridge.Commons.Types.Flattening;
using ZB.MOM.WW.ScadaBridge.SiteEventLogging;
using ZB.MOM.WW.ScadaBridge.SiteRuntime.Persistence;
namespace ZB.MOM.WW.ScadaBridge.SiteRuntime.Actors;
@@ -35,6 +37,14 @@ public class NativeAlarmActor : ReceiveActor
private readonly SiteRuntimeOptions _options;
private readonly ILogger _logger;
private readonly AlarmKind _nativeKind;
private readonly IServiceProvider? _serviceProvider;
/// <summary>
/// M1.5: severity at or above which a native-alarm raise is logged as
/// <c>Error</c> to the site event log; below it, raises log as <c>Warning</c>.
/// Mirrors the 0–1000 condition-severity scale.
/// </summary>
private const int ErrorSeverityThreshold = 700;
/// <summary>Current mirrored conditions, keyed by source reference.</summary>
private readonly Dictionary<string, NativeAlarmTransition> _alarms = new();
@@ -54,6 +64,9 @@ public class NativeAlarmActor : ReceiveActor
/// <param name="logger">Logger for diagnostics.</param>
/// <param name="nativeKind">Alarm kind to stamp on emitted events (OPC UA vs MxAccess); set by the
/// Instance Actor from the connection protocol. Defaults to <see cref="AlarmKind.NativeOpcUa"/>.</param>
/// <param name="serviceProvider">Optional DI service provider used to resolve the optional
/// <see cref="ISiteEventLogger"/> for M1.5 <c>alarm</c> operational events. Fire-and-forget;
/// a logging failure never affects the mirror.</param>
public NativeAlarmActor(
ResolvedNativeAlarmSource source,
string instanceName,
@@ -62,7 +75,8 @@ public class NativeAlarmActor : ReceiveActor
SiteStorageService storage,
SiteRuntimeOptions options,
ILogger logger,
AlarmKind nativeKind = AlarmKind.NativeOpcUa)
AlarmKind nativeKind = AlarmKind.NativeOpcUa,
IServiceProvider? serviceProvider = null)
{
_source = source;
_instanceName = instanceName;
@@ -72,6 +86,7 @@ public class NativeAlarmActor : ReceiveActor
_options = options;
_logger = logger;
_nativeKind = nativeKind;
_serviceProvider = serviceProvider;
Receive<RehydrationCompleted>(HandleRehydration);
Receive<NativeAlarmTransitionUpdate>(HandleTransition);
@@ -150,7 +165,10 @@ public class NativeAlarmActor : ReceiveActor
condition, string.Empty, string.Empty, string.Empty, string.Empty, string.Empty,
null, row.LastTransitionAt, string.Empty, string.Empty);
_alarms[row.SourceReference] = t;
Emit(t, t.Condition);
// M1.5: rehydration replays last-known state on (re)start — surface it
// upward for the DebugView but do NOT re-log it as a fresh operational
// event (it is not a live transition).
Emit(t, t.Condition, logSiteEvent: false);
}
}
@@ -277,8 +295,16 @@ public class NativeAlarmActor : ReceiveActor
}
}
/// <summary>Builds and tells the parent an enriched <see cref="AlarmStateChanged"/> for a condition.</summary>
private void Emit(NativeAlarmTransition t, AlarmConditionState condition)
/// <summary>
/// Builds and tells the parent an enriched <see cref="AlarmStateChanged"/> for a condition.
/// </summary>
/// <param name="t">The mirrored transition.</param>
/// <param name="condition">The condition state to surface (may differ from <paramref name="t"/>'s
/// own condition, e.g. a synthesised return-to-normal on snapshot swap).</param>
/// <param name="logSiteEvent">M1.5: when <c>true</c> (live + snapshot transitions), emit an
/// <c>alarm</c> operational event. Suppressed for SQLite rehydration so a node restart does not
/// re-log every last-known condition.</param>
private void Emit(NativeAlarmTransition t, AlarmConditionState condition, bool logSiteEvent = true)
{
var change = new AlarmStateChanged(
_instanceName,
@@ -301,6 +327,49 @@ public class NativeAlarmActor : ReceiveActor
};
_instanceActor.Tell(change);
if (logSiteEvent)
{
LogAlarmEvent(t, condition);
}
}
/// <summary>
/// M1.5: fire-and-forget an <c>alarm</c> operational event mirroring a native
/// condition transition. An active condition is a raise (severity by the
/// condition's severity); an inactive condition is a return-to-normal; an
/// acknowledge transition is informational. Resolved optionally and never
/// awaited so a logging failure cannot affect the mirror (matching the
/// established ScriptActor/ScriptExecutionActor pattern).
/// </summary>
private void LogAlarmEvent(NativeAlarmTransition t, AlarmConditionState condition)
{
var logger = _serviceProvider?.GetService<ISiteEventLogger>();
if (logger == null)
{
return;
}
string severity;
string message;
if (t.Kind == AlarmTransitionKind.Acknowledge)
{
severity = "Info";
message = $"Native alarm {t.SourceReference} acknowledged";
}
else if (condition.Active)
{
severity = condition.Severity >= ErrorSeverityThreshold ? "Error" : "Warning";
message = $"Native alarm {t.SourceReference} active (severity {condition.Severity})";
}
else
{
severity = "Info";
message = $"Native alarm {t.SourceReference} returned to normal";
}
_ = logger.LogEventAsync(
"alarm", severity, _instanceName, $"NativeAlarmActor:{_source.CanonicalName}", message);
}
private void PersistUpsert(NativeAlarmTransition t)