This page explains how subscribers consume lifecycle events without changing runtime execution.
Subscribers are consumers of the NeMo Relay event stream. They receive emitted lifecycle events and use them for observation, forwarding, export, or analysis. On native Rust, Python, Node.js, and FFI surfaces, event-producing calls enqueue subscriber delivery on a process-wide background dispatcher and return without waiting for subscriber callbacks or exporter work.
Events describe what happened. Subscribers are the components that watch those events.
That separation matters:
Middleware and subscribers can be registered at different levels depending on their lifetime and visibility.
Global subscribers remain active process-wide until they are removed.
Scope-local subscribers are owned by one active scope and disappear when that scope closes.
Deregistering a subscriber affects future emissions. Events that were already emitted carry a subscriber snapshot, so queued callbacks from that snapshot may still run after deregistration.
Plugins can install subscribers as reusable, configuration-driven runtime components.
Subscribers consume the canonical event stream. They do not define the event model. They react to it.
This lets plain subscribers, exporters, and tracing adapters share one runtime source of truth.
Subscribers are commonly used for in-process observation, counters, debugging, and exporter handoff.
Some subscribers stay inside the process and power custom logging, analytics, or debugging logic.
For host integrations that need a serialized event payload, use the event
object’s canonical JSON helpers instead of reconstructing payloads from native
attributes. Python subscribers can call event.to_dict() or event.to_json()
from the callback while still using the normal subscriber registration API.
This pattern is useful when an agent runtime, framework adapter, or plugin host already has its own lifecycle hooks but wants NeMo Relay to be the shared telemetry representation. The host integration maps those hooks into NeMo Relay scopes, LLM calls, tool calls, or marks. NeMo Relay emits the canonical ATOF event stream, and each subscriber chooses whether to consume the native event object, the canonical JSON helper, or an exporter-specific translation.
The important boundary is that subscribers do not define the event schema. They receive the runtime event and may serialize it through the binding helper when they need a stable JSON payload. Exporter subscribers, such as the ATOF JSONL exporter, consume the same event stream and serialize the same canonical event shape for their target backend.
Native subscribers are invoked by one process-wide worker thread in FIFO event order and subscriber snapshot order. WebAssembly keeps its current synchronous delivery behavior because this ticket does not add thread-based dispatch there.
Use the flush API when application shutdown, tests, or examples must observe side effects from subscriber callbacks that have already been queued:
nemo_relay::api::subscriber::flush_subscribers()?nemo_relay.subscribers.flush()flushSubscribers(), then await an event-loop tick for JavaScript
callback side effectsnemo_relay_flush_subscribers()flushSubscribers() succeeds as a no-opSome subscribers translate the event stream into external formats or transport it to another system.
Some subscribers derive measurements, trajectories, or diagnostics from the event stream without affecting execution behavior.
These examples show how built-in subscriber patterns relate to custom subscribers and exporters.
A plain custom subscriber is the right choice when you want in-process handling of the canonical event stream.
The Agent Trajectory Interchange Format (ATIF) exporter collects lifecycle events and emits trajectory artifacts for offline analysis, replay, or debugging.
The Agent Trajectory Observability Format (ATOF) JSONL exporter writes the canonical event stream to a native filesystem path as one raw ATOF event per line.
The OpenTelemetry subscriber maps runtime events into OTLP traces for tracing backends.
The OpenInference subscriber maps runtime events into OTLP traces using OpenInference semantics for model-centric observability.
Detailed setup, configuration, and API shape for these subscribers belongs in
Observability.
For configuration-driven setup, use the built-in
observability plugin
to install ATOF, ATIF, OpenTelemetry, and OpenInference subscribers from one
plugin component.
Use these practices when applying the concept in application or integration code.
event.to_dict() or event.to_json() when a host runtime or exporter
needs the canonical event JSON shape in-process.