Skip to main content
A NexusStreamObserver receives structured callbacks for every stream lifecycle transition. It is the way to wire SDK state into dashboards, custom telemetry, or load-test tooling - far more reliable than matching log lines. The observer is opt-in. Without one the SDK uses NexusStreamObserver.NOOP. The auto-configuration picks up any NexusStreamObserver bean; a plain client takes one through NexusConfig.builder().observer(...).

The interface

Every method has an empty default - implement only the hooks you care about.

Hook semantics

Fallback reasons

Every reason except service-locked reconnects on its own. Track the actual connection state with onConnected / onDisconnected or client.isStreamConnected().

Threading contract

Observer methods are called synchronously from the SDK’s stream thread and must return promptly - a slow callback delays the stream. An observer that throws is contained: the exception is logged and the stream carries on.
If your observer does anything substantial (network I/O, lock contention, disk writes), copy the argument and hand the work to your own executor before returning.

Spring Boot bean wiring

No further wiring is needed - the auto-configuration passes the bean to the client.

Counter pattern