LocusReliabilityRegistry class
Singleton that holds the SDK's reliability event stream and counters.
The public surface (Locus.reliability, Locus.metrics) is a thin
re-export of this registry. Internal SDK code (sync, storage, quarantine
janitor, ...) calls the record* / emit methods to feed it.
Per-isolate scope
instance is a static final inside this Dart library, which means
one registry per Dart isolate, not one per process. Headless
callbacks (geofence triggers, sync-on-boot) execute in a secondary
isolate spawned by the Flutter engine. Events that fire there land in
that isolate's registry, not the foreground app's.
Practical consequences for embedders:
- Subscribing to
Locus.reliabilityfrom a Riverpod provider only sees events emitted from the foreground isolate. Locus.metrics.snapshot()read from the foreground only reflects foreground-side counters — captures and syncs that happen during headless execution don't show up there.- Background-isolate observability is best read via the structured logs
the SDK emits (e.g.
tracking_heartbeat), which the platform side forwards into the unified log stream.
Plumbing headless events into the foreground registry would require a platform-channel bridge with explicit ordering guarantees and is tracked as a follow-up.
Properties
- hashCode → int
-
The hash code for this object.
no setterinherited
- metrics → LocusMetrics
-
Public read-only metrics view.
no setter
-
reliability
→ Stream<
LocusReliabilityEvent> -
Public stream of reliability events.
no setter
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
- syncHealthMonitor → SyncHealthMonitor?
-
Currently installed sync health monitor, if any. Internal callers may
use it to call
SyncHealthMonitor.evaluatefrom a heartbeat tick.no setter
Methods
-
emit(
LocusReliabilityEvent event) → void - Emit a reliability event to subscribers. Safe to call at any time: after resetForTests closes the controller, the next call will see a fresh broadcast stream.
-
installSyncHealthMonitor(
SyncHealthMonitor monitor) → Future< void> -
Installs a
SyncHealthMonitor. Detaches and replaces any previously installed monitor. -
installSyncMetricsRecorder(
SyncMetricsRecorder recorder) → Future< void> -
Installs a
SyncMetricsRecorder. Detaches and replaces any previously installed recorder. Held by the registry so the subscription stays alive without callers needing to hold the reference themselves. -
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
recordCaptured(
int count) → void - Increment the captured-points counter.
-
recordDropped(
int count) → void -
Record an eviction (queue overflow or age limit) that dropped
countpoints. Increments the cumulativepointsDroppedcounter. -
recordSent(
int count, {DateTime? at}) → void -
Record a successful sync that flushed
countpoints. -
recordSyncFailure(
{int? httpStatus, DateTime? at}) → void - Record a failed sync attempt. Optionally carries the HTTP status seen.
-
resetForTests(
) → Future< void> - Resets the registry to a pristine state. Intended for tests only. Closes the existing event stream and creates a fresh one.
-
setQuarantinedNow(
int count) → void - Update the current quarantine size. This is a gauge, not a counter, so the value is replaced wholesale.
-
toString(
) → String -
A string representation of this object.
inherited
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited
Static Properties
- instance → LocusReliabilityRegistry
-
Per-isolate singleton — see the class-level dartdoc on isolate scope.
final