The Reactive metrics collection toolkit for the VLINGO XOOM platform.

Use XOOM Telemetry for measure performance, throughput, and latency, for your project components. This is currently an experimental tool and at this time supports XOOM Actors by way of tapping mailboxes.

The following is a brief usage guide.

Usage Guide

XOOM Telemetry provides a telemetry registry that can be used within any actor to push metrics to your APM or monitoring system. By default, XOOM Telemetry uses an implementation backed by Micrometer, so most common backends are supported, including JMX, Prometheus, and StatsD.

Registering the Telemetry Registry

XOOM Telemetry provides a Telemetry object that will be used by actors to push metrics. The easiest way to register the Telemetry object is by using the DefaultTelemetryProvider, which will create a MicrometerTelemetry that exports all it's metrics to JMX. The snippet to configure telemetry follows.

// Probably you will already have a World defined with your own configuration :)
World world = World.startWithDefaults("measurements");

// The DefaultTelemetryProvider uses Micrometer
TelemetryProvider<MeterRegistry> telemetryProvider = new DefaultTelemetryProvider();

// Provides a Telemetry registry based on the created world
Telemetry<MeterRegistry> telemetry = telemetryProvider.provideFrom(world);

// Registers the telemetry object in the world
world.registerDynamic("telemetry", telemetry);

Sending Metrics From Actors

All actors hosted by XOOM Actors live in a Stage, each of which is part of a World. All actors through their World can access the Telemetry provider and send metrics to the registry asynchronously, thus reducing the performance impact of monitoring actors.

The Telemetry object is usually acquired by the actor during the instantiation, as it will be needed during the whole lifecycle of the actor. A single instance is all that is needed. To provide some context, consider the following example.

Here's a Counter protocol to be implemented by an actor. The actor will count seconds and, on each second, send a metric with the counter to the registry.

public interface Counter {
    void count();

The protocol now requires and actor to implement it in order to provide behavior. Create a new CounterActor class that, implementing Counter, performs the business of counting. First note the constructor.

public class CounterActor extends Actor implements Counter {
    private final Telemetry<?> telemetry;
    private final String name;

    public CounterActor(String name) {
        this.telemetry = Telemetry.from(this.stage().world()); // <-- getting the telemetry! = name;

    public void count() {
        // will focus later on this

Because the Telemetry object lives in the same World as the actor, the instance is available from the actor's World reference. By getting the registered Telemetry, it's now possible to send metrics at will from inside the actor. Next consider the count() behavior.

public void count() {
    telemetry.count("Count", 1, Telemetry.Tag.of("Name", name));

That's it.

One-liners deserve explanation, even though the telemetry design is rather intuitive. The telemetry count method contains three parameters:

If you are using the default telemetry provider, as in this example, you can see the metrics using the JConsole that comes with your JDK. Connect to the local process using debugging.

The Telemetry provide three different methods to send metrics, with different use cases. We've already seen count .

Integration With Actors

XOOM Actors provide a plugin mechanism that allows XOOM Telemetry to supply a mailbox provider, and thus automatically measure the amount of messages and processing time, per actor. This is really useful for monitoring systems in production, as the low number of messages and processing time in actors indicates that the system is healthy.

The recommended way to plug in the mailbox telemetry is before starting the World. The easiest way to accomplish that is by using the file. Adding the plugin should be enough to have all the metrics ready to read through JMX. = true
plugin.telemetry.classname = io.vlingo.xoom.telemetry.TelemetryPlugin = true
plugin.mailboxTelemetry.classname = io.vlingo.xoom.telemetry.plugin.mailbox.MailboxTelemetryPlugin

The plugin provides the following metrics aggregated by the actor class. All metrics are tagged with the address of the actor, so metrics can be gathered also by actor.

Using the properties file is recommended most of the times as it simplifies configuration and can be handled relatively easily and versioned without changing Java code. However, to use the file, you will need to start your world with the start() method instead of startWithDefaults(). Any previously used plugin configuration using Java code is no longer needed as it is replaced by the properties configuration.

Because the VLINGO XOOM platform is built entirely on actors, all internal actors are also monitored, so metrics for the DeadLettersActor (for example) can also be monitored as easy as server/application actors. This will be plugged in for all actors: Journal instances, XOOM HTTP servers, queue consumers, and all others can be monitored with no additional effort.

Using a Custom Micrometer Provider

XOOM Telemetry, by default, exports all the information to JMX. However, in production setups, you might desire to export metrics to more reliable platforms, such as Prometheus, StatsD, CloudWatch, etc. Micrometer already works out of the box with all of the aforementioned, so XOOM Telemetry can be adapted to export your service/application metrics as well.

To do so, create a new TelemetryProvider and implement the provideFrom() method to return a new Telemetry object that is set up for the desired observation console. Here's an example for DataDog.

public class DatadogTelemetryProvider implements TelemetryProvider<MeterRegistry> {
    public Telemetry<MeterRegistry> provideFrom(World world) {
        DatadogConfig config = new DatadogConfig() {
            public Duration step() {
                return Duration.ofSeconds(10);

            public String apiKey() {
                return "YOUR_API_KEY";

            public String get(String k) {
                return null; // accept the rest of the defaults

        MeterRegistry registry = new DatadogMeterRegistry(config, Clock.SYSTEM);
        return new MicrometerTelemetry(registry);

XOOM Telemetry does not provide all Micrometer dependencies, only the core. If you want to use DataDog with Micrometer, you will need to add the dependency to your build.gradle or pom.xml as explained in the documentation for Micrometer. The same goes for other observation tools.

Given the use of DataDog, define the appropriate provider in the properties file. = true
plugin.telemetry.classname = io.vlingo.xoom.telemetry.TelemetryPlugin
plugin.telemetry.providerClass = com.myapp.infrastructure.DatadogTelemetryProvider

Our team welcomes your feedback and contributions for improving the XOOM Telemetry functionality.

Last updated