Legacy io.Insights

The Metrics API is accessible through the io.metrics object.

Metrics are organized in a hierarchical structure using System objects. Systems can have sub-systems and metrics. Аll metrics and metric sub-systems are created under a common App system, which sits under the root (/) system.

To create a sub-system, you need to have a reference to a system and call its subSystem() method. Initially, there is one root system available.

The following example demonstrates how to create a sub-system by passing a name and description for it:

const module = io.metrics.subSystem("Module", "App Module");

You can create almost arbitrary in structure and in depth metrics systems:

const module = io.metrics.subSystem("A").subSystem("B");

// Or

const module = io.metrics.subSystem("A/B/C");

The value of creating sub-systems is that it allows you to independently group attributes of your system and to flag its state. To set the state, use the setState() method which accepts a state number and a state description as arguments:

// State RED, nothing works.
module.setState(100, "Disconnected from backend.");

// State GREEN, everything works.
module.setState(0, "Connected to backend.");

// State AMBER, some problems.
module.setState(50, "Backend operational but some endpoints aren't available.");

The state is a number between 0 and 100 and the description argument is a string explaining the state.

The root system is io.metrics, but it can also be accessed via the root property of any system:

const root = module.root;

To find the parent of any sub-system, use the parent property. To retrieve the child systems of a system, use the subSystems property.

Metric Types

The Metrics library offers the following subsets of io.Connect Metrics:

Creating Metrics

The following examples demonstrate how to create different types of metrics. The methods for creating metrics are available at top level of the API, as well as on the System instance, except for the FAV metric method which is available only at top level.

To create a FAV metric, use the featureMetric() method:

// The FAV metric method is available only at top level of the API.
io.metrics.featureMetric("Info View", "Selected", "grid");

To create a string metric, use the stringMetric() method:

// String metric created under a metric sub-system.
const stringMetric = module.stringMetric("io.Connect Version", io.version);

To create a number metric, use the numberMetric() method:

// Number metric.
const numberMetric = module.numberMetric("Failed Requests", 1);

To create a timestamp metric, use the timestampMetric() method:

// Timestamp metric.
const timestampMetric = module.timestampMetric("Time", Date.now());

To create an object metric, use the objectMetric() method:

const error = {
    message: "Critical module error.",
    time: Date.now()
};

// Object metric.
const objectMetric = module.objectMetric("Last Error", error);

Updating Metrics

Metric values are updated using the update() method of the metric instance and the NumberMetric also has methods for incrementing and decrementing its value:

// Updating string metrics.
await stringMetric.update(io.version);

// Updating number metrics.
await numberMetric.update(2);
numberMetric.increment();
numberMetric.decrement();
numberMetric.incrementBy(1);
numberMetric.decrementBy(2);

// Updating timestamp metrics.
await timestampMetric.update(Date.now());

// Updating object metrics.
await objectMetric.udpate({ io: 42 });

Try to instrument your app as early as possible. Almost any web app performs a lot of AJAX requests, typically over REST calls to manipulate resources. Avoid simply using your favorite AJAX library function everywhere. Instead, you should create a wrapper function which calls it.

Maintain a metrics system for each endpoint, set its state to 100 (RED) when the request fails, and back to 0 (GREEN) when the request succeeds. Then, under each system:

• use number metrics to count the number of requests, the number of failures and the number of successes;
• use have timestamp metrics to record min/max/average latency;
• use an object metric to record the last reason for failure (time of occurrence, message, and stack trace, if possible);

Wrapping the function also gives you the ability to mock responses for testing, show and hide progress widgets in a consistent way, etc.

If you have instrumented your app properly, you should be able to debug any problem without having to look at log files, even if the problem is with the backend.

Avoid leaking personal information (IDs are OK, names aren't, URLs should be fine).

For a complete list of the available Metrics API methods and properties, see the Metrics API Reference Documentation.