The Toolkit #1

The Concept Catalog

The Substrates project provides a cohesive and coherent set of concepts and contracts that we have found as repeating structural and behavioral patterns across our past, present, and future library designs. In the past, we mostly replicated many of these concepts to some degree across each library. Still, with the Humainary initiative, we’ve opted this time around to pull them out in a separate module shared across all instrument libraries.

Instead of having a Name interface defined in a Probes API and a Metrics API, we now package up the same form and specification within the Substrates project. This ensures we can maintain a common language of concepts and contracts across projects, offering re-use at the concept, code, and communication levels – keeping libraries small.

The Name Interface

Anywhere within a Humainary instrument library that involves a lookup of an instrument or state value is done by providing a Name instead of the unfortunate common use of String. Names are used to identify instruments within a Context and configuration values accessible via the Environment interface. A Name is a sequence of string value parts, much like a domain name or code namespace.

Using a Name, as opposed to a String, the underlying implementation can implement sophisticated optimizations in terms of performance and memory footprint while offering extended methods that support ease of usage for common patterns.

We are determined that all Humainary observability libraries and technologies be also applicable in low-latency environments, which is not the case for what we currently see offered by the open-source community or application performance monitoring vendors.

The Environment Interface

The Environment interface is an abstraction for interfacing with configuration systems and (files) stores, including in-memory state values. It is a read-only interface, though it offers methods that allow chaining multiple Environment instances to provide defaults and overriding values.

We employ the Environment interface within instrument libraries to create and configure a Context or Plugin. In addition, the Phaneros project uses it as a novel replacement for eventing, seeing an event as a composition of nested state enclosures as opposed to one big fat flat property struct that tries to cover all bases at excessive computation and communication costs.

The Substrates project is designed with local consumption being the default expected data collection behavior. We believe the future of observability is not big fat expensive pipelines reaching out to an endpoint obscured by cloud but distributed intelligence at the edge embedded within services coupled with autonomic adaptive control for responsive actioning.

The Variable Interface

A Variable is a utility interface used for efficiently retrieving a value from a provided Environment. A Variable can be substituted for code that looks up a state value within the Environment using a Name reference. A Variable is created with the same Name reference. The benefit of this additional lookup method is that it allows the underlying implementation of the service provider interface (SPI) to micro-optimize retrievals at call sites.

A Variable, much like a Name, can be a static constant field within a class; only the Environment brings the dynamics to the code.

Example Code Listing

package io.humainary.substrates.samples;

import static io.humainary.substrates.Substrates.*;

public final class Level1 {

  private static final Name NAME =
    name ( "io" )
      .name ( "substrates" );

  private static final Variable< String > VARIABLE =
    variable (
      NAME,
      "default"
    );

  private static final String VALUE = "value";

  public static void main (
    final String[] args
  ) {

    // name instances are interned

    assert
      name ( "io.substrates" )
        == NAME;

    // utility methods can be used to
    // create an environment on the fly

    final var environment =
      environment (
        NAME,
        VALUE
      );

    // looking up a state value
    // using a name and environment

    assert
      environment.getString (
        NAME,
        null
      ).equals (
        VALUE
      );

    // with the variable we don't
    // need to ref a name or default

    assert
      VARIABLE.of (
        environment
      ).equals (
        VALUE
      );

  }

}