Composing Instrument Circuits

The Substrates API makes it painless to create observability Circuits, where Events from one type of Instrument, resulting from client calls, can be consumed and reinterpreted as an operation on another type of Instrument. This benefits instrumentation agents and self-adaptive applications that use such Events to change call paths and adjust self-regulating mechanisms.

In this post, we walk through one of the showcases in the project’s code repository that demonstrates how the complexity of hooking up components in a Circuit is greatly simplified. In the example, there are two basic types of Instruments. The first type of Instrument, considered a sensor, allows a client to publish an int value. The second Instrument type, considered an observer, publishes a boolean value, a flag, which could be an indicator of sorts within a control panel. An Outlet will be the glue that consumes an Event from the sensor Instrument and reinterprets it using a predicate before forwarding it to the observer Instrument.


The first step is to create a Circuit; both Conduits and the Instruments they manage will share this Circuit in their Event publishing and processing. Like Thread pools for service request scaling, Circuits are blocking buildings for pipeline scaling.

With the Circuit created, the first Conduit, representing a sensory level, can be created. Generally, a Conduit is created with a specific Instrument type, such as a Counter, Timer, Probe, Valve, etc. Here a built-in type, Publisher, is used for conciseness.

The second Conduit is created similarly but with the Event emittance class type changing from Integer to Boolean.


With both Conduits created, a Subscriber can now subscribe to the first Conduit, the sensors, that will create a corresponding Instrument with the Conduit managing the observers whenever a sensor is created. The Subscriber also registers an Outlet with each sensor Instrument created. The Outlet is the relay within the circuitry in that it takes the output from a named sensor. It transforms it into an input to the same named observer, going from a raw sensor int input to a derived observer boolean output.


All that is left now is to feed data into the input layer of the Circuit by creating a named Instrument from the sensors named Conduit and emitting values. The following code will result in four Events following through the pipeline of the Circuit.

Registering an Outlet with both Conduits that prints the Subject and emittance of an Event results in the following output.

The full Java source code listing can be found here.