Skip to main content
Pass an IStreamObserver via NexusConfig.Observer to receive structured callbacks for every SSE lifecycle transition. The observer is the canonical way to wire SDK state into ops dashboards, custom telemetry, or load-test tooling - far more reliable than scraping log output by substring match. The observer is opt-in. When NexusConfig.Observer is null the SDK uses its no-op observer at zero overhead. On the dependency-injection path, register it in the container instead: services.AddSingleton<IStreamObserver, MyObserver>().

The interface

Every hook has an empty default, so an observer implements only the ones it needs:

Hook semantics

OnFallback reasons

For every reason except ServiceLocked, the SDK reconnects on its own and a later OnConnected() confirms the stream is back. See SSE live updates for the connection limits.

Threading contract

Observer methods are called synchronously from the SDK’s stream-reader Task. They MUST return promptly. The SDK does not protect against blocking observers and does not wrap the calls in Task.Run.
If your observer does anything substantial (network I/O, lock contention, disk writes), copy the argument and dispatch the work to your own pipeline before returning:

Counter pattern

Active-connection gauge pattern

The gauge reads false from the moment the stream drops until the SDK’s own reconnect fires OnConnected() again - the same answer NexusClient.IsStreamConnected gives, for a health check that only needs to read it.

Per-event-type counter

A throwing callback

Every hook is invoked through one guarded dispatcher: a callback that throws has its exception absorbed and logged with the hook name, and the SDK carries on. Nothing a consumer’s observer does can end the stream or be counted as a transport error. Implementations should still return promptly - the SDK calls them synchronously from its own task and does not protect against a blocking observer. Copy the argument and dispatch the work to your own task if it needs to do anything substantial.