Instrument
When an Instrument is created, via a Cartridge, in the Substrates API, it is provided the Name associated with the Instrument instance and a Hub it can use to create an Inlet that will allow the Instrument to emit values that become Events when there are Subscribers to the associated Conduit. There are two methods in the Hub interface for this purpose – unicast and multicast. In this post, both Inlet creation methods are explored using a showcase example in the project, which can be viewed here.
Inlet
The typical flow of execution for an observability Instrument is for instrumentation code within the application code space to make a single call to a method defined in the Instrument extension interface. The Instrument implementation then emits a value to the Inlet given in its constructor. This emittance can be captured from the environment or provided by the method’s invocation via one or more parameters. In most cases, the emittance will result in a single Event being dispatched to one or more Subscribers, where the Name of the Event’s Subject is the Name assigned to the Instrument. Any fan-out of calls only occurs at the Subscriber level.
Inlet
But there are exceptional cases where a single call into an Instrument interface causes the dispatching of multiple Events. One such case is the Java Logger interface, which dispatches a LogRecord to Handlers at multiple points in a hierarchical namespace.
The Logger API’s namespace, represented as a plain old String, is the Name interface in the Substrates API. The LogRecord class is the equivalent of the Substrates Event interface, and Handler is an Outlet registered by a Subscriber. There is no concept of contextual enclosures such as the Substrates Circuit or Conduit interfaces in the Logger API because everything is global. Yikes!
Logger
Let’s create a Logger Instrument with the Substrates API, to demonstrate how easy it is to switch from single-event-dispatch mode to multi-event-dispatch mode without changing the implementation of the Instrument other than a change to the Cartridge setup.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
class Logger implements Instrument< String > { private final Inlet< Logger, String > inlet; Logger ( final Inlet< Logger, String > inlet ) { this.inlet = inlet; } void log ( final String message ) { inlet.emit ( message ); } } |
Changing from the typical Instrument behavior of one emittance resulting in one Event being dispatched with the Event’s Subject Name being the Instrument’s Name requires the following minor modification to the source code in creating a Conduit.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
// emit an event for the logger's fully qualified name final var conduit = circuit.conduit ( Cartridge.of ( Logger::new ) ); // emit an event for each part of the logger's name final var conduit = circuit.conduit ( Cartridge.of ( Hub::multicast, Logger::new ) ); |
Conduit
The Event pipeline processing behavior change can be checked with the following code, which along with creating a Circuit and Conduit, sets up an Outlet that prints each Event created when a Logger is called to log a String message.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
final var subscription = conduit .source () .consume ( event -> out.printf ( "%s from %s%n", event.emission (), event .subject () .reference () .name () ) ); final var logger = conduit.instrument ( cortex.name ( Inlets.class ) ); logger.log( "Hello, World!" ); |
Console
The following is printed if the above code is called with a Cartridge created from the Cartridge.unicast() method.
>_
Hello, World! from io.humainary.showcase.substrates.Inlets
Using the Cartridge.multicast() method, an Event will be dispatched for each namespace part of the Instrument’s Name.
>_
Hello, World! from io.humainary.showcase.substrates.Inlets
Hello, World! from io.humainary.showcase.substrates
Hello, World! from io.humainary.showcase
Hello, World! from io.humainary
Hello, World! from io