lmxopcua/docs/v2/Galaxy.Performance.md

Galaxy backend performance

This document covers the performance surface of the in-process GalaxyDriver (the v2 mxgw backend) — the ActivitySource it emits, the metrics on its EventPump, the soak scenario that validates it, and the tuning knobs you can reach for when the dev parity rig surfaces a hot spot.

Tracing surface (PR 6.1)

The driver emits spans on the ZB.MOM.WW.OtOpcUa.Driver.Galaxy ActivitySource. No package dependency on OpenTelemetry — the host process picks the listener (OTLP exporter, dotnet-trace, Application Insights). Wire it via OpenTelemetry.Trace.AddSource(...) in the host's tracing pipeline.

Span	Source	Tags
galaxy.subscribe_bulk	TracedGalaxySubscriber	galaxy.client, galaxy.tag_count, galaxy.buffered_interval_ms, galaxy.success_count
galaxy.unsubscribe_bulk	TracedGalaxySubscriber	galaxy.client, galaxy.tag_count
galaxy.stream_events	TracedGalaxySubscriber	galaxy.client, galaxy.event_count (set on stream end)
galaxy.write	TracedGalaxyDataWriter	galaxy.client, galaxy.tag_count, galaxy.secured_write_count, galaxy.success_count
galaxy.get_hierarchy	TracedGalaxyHierarchySource	galaxy.client, galaxy.object_count

The stream-events span deliberately covers the entire stream lifetime rather than per-event spans — at 50k tags / 1Hz the per-event volume would dominate the trace pipeline. Per-event visibility flows through the metrics surface instead.

Metrics surface (PR 6.2)

EventPump publishes three counters on the ZB.MOM.WW.OtOpcUa.Driver.Galaxy meter, each tagged with galaxy.client so multi-driver hosts can split by source:

Counter	Unit	Meaning
galaxy.events.received	{event}	MxEvents read from the gateway StreamEvents stream
galaxy.events.dispatched	{event}	MxEvents that made it through the bounded channel into OnDataChange
galaxy.events.dropped	{event}	MxEvents discarded because the bounded channel was full (newest-dropped)
galaxy.events.replay_gaps	{gap}	Replay-gap sentinels received — the gateway evicted events we can never see
galaxy.events.undecodable	{event}	Data-change events carrying a value kind this driver cannot represent

The invariant is received = dispatched + dropped + replay_gaps + (in-flight in the channel). A replay-gap sentinel is counted as received but never enters the channel — it is a control signal with no item payload, handled on the read loop precisely so channel pressure can never drop it.

Watch the dropped counter — it is the leading indicator of listener back-pressure. A non-zero dropped rate means a downstream consumer (DriverNodeManager → UA notification queue → client) is slower than the gw event stream; investigate that consumer before raising EventPump channel capacity.

galaxy.events.replay_gaps should be flat at zero, for a structural reason rather than a healthy one: the gateway only emits the sentinel on a stream opened with after_worker_sequence > 0, and the driver opens with 0 ("fresh stream, not a resume"). A non-zero value therefore means the resume path was enabled — each gap costs a full re-subscribe of every tag on the driver, so a climbing counter is a sizing problem, not just an observation.

galaxy.events.undecodable should likewise be flat at zero: every MxValue kind the contract declares decodes today. Non-zero means the gateway shipped a new wire type, and those readings are being published as BadTypeMismatch with a null value — visible to clients as bad data rather than as a plausible null, and logged once per distinct kind. The remedy is a mapping in MxValueDecoder, not a quality change.

Bounded channel design

The pump runs two background tasks:

1. Producer — reads from IGalaxySubscriber.StreamEventsAsync, increments events.received, and TryWrites into a bounded Channel<MxEvent>. When the channel is full, the producer counts the drop and continues reading the gw stream so back-pressure does not propagate upstream (which would stall the gw worker and cascade to all driver instances sharing that worker).
2. Consumer — reads from the channel, fans out via SubscriptionRegistry, increments events.dispatched.

Default channel capacity is 50_000 (one second of headroom at 50k tags / 1Hz). Override via the EventPump constructor's channelCapacity parameter; the public-facing wiring path in GalaxyDriver.EnsureEventPumpStarted does not yet expose this through GalaxyDriverOptions because no parity scenario has needed it. Add it when soak data does.

Buffered update interval (PR 6.3)

MxAccess.PublishingIntervalMs (default 1000) flows through both subscribe paths:

• GalaxyDriver.SubscribeAsync — the caller's publishingInterval wins when non-zero (the server's UA subscription publishingInterval drives this in production). When the caller passes TimeSpan.Zero, the configured option is the fallback.
• PerPlatformProbeWatcher — the watcher passes the configured value through SubscribeBulkAsync so probe ScanState changes publish at the deployment's chosen cadence.

A session-level SetBufferedUpdateInterval RPC exists in the gw protocol but the .NET client doesn't expose a typed helper yet — adjusting an existing subscription's interval mid-flight is a follow-up. Today's path subscribes once at the right interval, which covers the common case.

Soak scenario (PR 6.4)

SoakScenarioTests.Soak_HoldsSubscription_AndKeepsEventStreamFlowing in Driver.Galaxy.ParityTests is the long-running validation. It subscribes a configurable tag count (default 50_000), holds the subscription for a configurable duration (default 24h), polls the three counters every minute, and asserts:

• events.received continues to grow (gw stream isn't stuck)
• events.dropped / events.received stays under the configured ceiling (default 0.5%)
• process working-set doesn't grow more than 1 GB above baseline (leak guard)

Always skipped unless the operator opts in:

# Full 24h × 50k soak (production validation)
OTOPCUA_SOAK_RUN=1 dotnet test tests/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.ParityTests/

# Compressed CI-friendly run (10min × 1k tags, 1% drop ceiling)
OTOPCUA_SOAK_RUN=1 OTOPCUA_SOAK_MINUTES=10 OTOPCUA_SOAK_TAGS=1000 \
  OTOPCUA_SOAK_DROP_PCT=1.0 \
  dotnet test tests/ZB.MOM.WW.OtOpcUa.Driver.Galaxy.ParityTests/

The scenario writes a per-minute CSV-style row to stdout (soak,<minutes>,received=…,dispatched=…,dropped=…,ws_mb=…) so an operator can grep the test runner output mid-run.

Tuned defaults (PR 6.5)

Option	Default	Source	Notes
Gateway.ConnectTimeoutSeconds	10	unchanged	Cold-start network paths fit comfortably; soak never observed >2s
Gateway.DefaultCallTimeoutSeconds	30	bumped from 5 in PR 6.5	A 50k-tag SubscribeBulk can exceed 5s under MxAccess COM apartment lock contention; 30s leaves headroom while still failing fast on a wedged worker
Gateway.StreamTimeoutSeconds	0 (unlimited)	unchanged	The stream must run for the lifetime of the driver
MxAccess.PublishingIntervalMs	1000	unchanged	Matches the legacy LMXProxyServer cadence; deployments needing tighter health visibility can dial down
Reconnect.InitialBackoffMs	500	unchanged	First retry shouldn't dogpile a recovering gw
Reconnect.MaxBackoffMs	30_000	unchanged	30s ceiling so a long-down gw doesn't sit in 5+ min backoff
Repository.DiscoverPageSize	5000	unchanged	One Galaxy page round-trip per ~5k objects; soak hadn't surfaced pressure
EventPump channel capacity	50_000	unchanged	One second of headroom at 50k tags / 1Hz

The unchanged rows are not "definitely correct" — they are "no live data argues for changing them." Re-run the soak scenario after every substantive driver change, and revise this table when the data does.

Where to look first when something's slow

1. Slow Discover? Inspect galaxy.get_hierarchy span duration and galaxy.object_count. The gw walks the Galaxy DB serially; slow Discovers usually mean a slow ZB SQL.
2. Subscribe pile-up? galaxy.subscribe_bulk span duration correlates with galaxy.tag_count. If duration ÷ tag_count starts climbing, the gw worker is probably under apartment-lock pressure.
3. Events stalled? Watch galaxy.events.received. Flat-lined means the gw stream is wedged — kick the reconnect supervisor by forcing a ReinitializeAsync.
4. Dropped events? Non-zero galaxy.events.dropped means a slow downstream consumer. Profile OnDataChange handlers in DriverNodeManager before bumping the channel capacity.
5. Memory growing? Confirm with the soak scenario's working-set leak guard. Likely culprits: lingering subscription handles in SubscriptionRegistry, or a downstream consumer retaining DataValueSnapshot references past their useful life.

Scripted-alarm engine — hot-path allocation reuse

ScriptedAlarmEngine keeps a per-alarm reusable evaluation scratch in _scratchByAlarmId — the read-cache Dictionary<string, DataValueSnapshot> and the AlarmPredicateContext are allocated once per alarm (on first evaluation) and refilled in place across every subsequent predicate evaluation. The hot path no longer allocates a fresh dictionary + context per upstream tag change. (Core.ScriptedAlarms-009)

Safety: reuse is serialised under _evalGate, so two threads can never observe the same scratch in a half-refilled state. The context wraps the read-cache by reference, so refilling the dictionary is what the predicate's ctx.GetTag(path) calls observe. LoadAsync clears _scratchByAlarmId alongside _alarms so a config-publish drops the prior generation's scratch (a new generation may carry different Inputs / Logger). Regression tests in ScriptedAlarmEngineTests lock the reuse contract:

• Reevaluation_reuses_the_same_read_cache_dictionary — asserts dictionary instance identity across two evaluations.
• Reevaluation_reuses_the_same_predicate_context — same, for the context.
• LoadAsync_drops_the_prior_generations_scratch — asserts a publish resets the scratch.

Value-path batching (2026-08-15)

The hot value path is batched end to end: one message per driver production burst (a poll cycle, an inbound message, a stream chunk) instead of one per changed tag at every hop, one SDK-lock acquisition per batch instead of one per value, and no per-write key allocation in the node manager. Nothing about what is published changed — only how many messages and lock takes it costs. Plan + task-by-task rationale: docs/plans/2026-08-15-value-pipeline-batching.md.

The seams, in order:

• IBatchSubscribable / PollGroupEngine's onBatch — an optional driver capability raising OnDataChangeBatch once per burst. The four engine-based poll drivers (Modbus, S7, AbCip, FOCAS) get it from the engine's batch callback. The per-tag ISubscribable.OnDataChange is unchanged and still raised — Galaxy cold reads and the driver CLIs subscribe it. A consumer subscribes to exactly one of the two; subscribing both double-delivers.
• DriverInstanceActor → AttributeValueBatchPublished — one per burst, preferring the batch event when the driver implements IBatchSubscribable and wrapping a non-batch driver's per-tag events as single-item batches, so downstream sees one shape. The detach path tears the batch handler down too (load-bearing: the IDriver outlives the actor across host respawns).
• DriverHostActor → AttributeValueBatchUpdate — resolves the whole batch's NodeRealmRefs (raw NodeId + every referencing UNS NodeId) and sends one message to OpcUaPublishActor, plus one batch Tell to the dependency mux. The mux keeps its per-item receive — the comms-loss fan-out fabricates per-item messages.
• OtOpcUaNodeManager.WriteValues — the sink's batch override takes the manager-wide Lock once per chunk of 512 items rather than once per value, with each item isolated so one bad node cannot lose the rest of the batch.

Invariants the batching preserves — do not break them:

• #519 status codes ride verbatim. The full uint status code, sub-code included, reaches the SDK unchanged at every hop; batching moved the values, it did not re-derive them. Timestamps likewise come from the driver — nothing on this path stamps DateTime.UtcNow.
• Metering stays per ITEM, not per batch (OpcUaPublishActor's write tally + the OtOpcUaTelemetry.OpcUaSinkWrite meter). Counting per message would have silently dropped the dashboards by up to 100×.
• Deadband is honored on the batch event. ⚠️ PollGroupEngine collects its batch list unconditionally — it has no knowledge of a driver's publish filter — so ModbusDriver ignores the engine's list and raises from its own buffer of what actually passed ShouldPublish, using onBatch purely as the end-of-cycle signal. Forwarding the engine's list instead would carry changes the per-tag event suppressed, and a consumer preferring the batch event would see deadband silently stop working.
• Partial failure is typed, not swallowed. A sink that applies some of a batch and fails the rest reports ValueWriteBatchException (first failed NodeId + failed/succeeded counts); the publish actor's typed catch advances the tally by the succeeded count — not zero (the general catch's behaviour) and not the whole batch.

Two supporting changes: the node manager's variable / folder / alarm / historized-tagname maps are re-keyed by a RealmKey(Realm, Id) struct, so a write no longer allocates new NodeId(id, ns).ToString() per value (the realm still travels explicitly — it is never parsed back out of an id string). And the pinned opcua-synchronized-dispatcher's throughput rose 1 → 100: the actor keeps its own dedicated thread (that is what the PinnedDispatcher guarantees, not throughput), so this only removes a mailbox re-schedule round-trip per message on the hottest actor in the process, with zero change to concurrency. Keep it in sync with the inline HOCON copy in ServiceCollectionExtensions.WithOtOpcUaRuntimeActors.