What are metrics?

Metrics are a simple way to maintain various counts based on Message contents and metadata. You choose what to measure and Splitlog will make sure that the metric is updates every time a new Message is received.

A measure is a user-provided class that implements the MessageMeasure interface. The interface requires you to provide the following:

1. Numeric type to calculate in. It is entirely up to you and would typically be Integer, altough other alternatives like BigDecimal will work equally well.
2. Initial value of the metric. Most typically zero, in the representation typical for the chosen numeric type.
3. Implementation of the update() method that will take current value of the metric and update it based on the Message being processed.

Users are encouraged to implement these as stateless. Otherwise, unpredictable behavior can occur, as the measures may be shared across multiple metrics.

Using metrics on Followers

The most typical use case would be to measure the number of Messages that come through your Follower. Here’s how you do that; first, create your MessageMeasure implementation:

  MessageMeasure<Integer, LogWatch> messageCounter = new MessageMeasure<Integer, LogWatch>() {

    @Override
    public Integer initialValue() {
        return 0; // start with zero
    }

    @Override
    public Integer update(MessageMetric<Integer, LogWatch> metric, Message evaluate, MessageDeliveryStatus status, LogWatch source) {
        if (status != MessageDeliveryStatus.ACCEPTED) {
            // don't increment for INCOMING messages
            return metric.getValue();
        } else {
            // one fully processed new message in the log
            return metric.getValue() + 1;
        }
    }

  };

Fairly straight-forward, isn’t it? You may want to check out what the MessageDeliveryStatus is though, in the Message Lifecycle chapter. Now, let’s move on to how you convert this into a working metric.

  Follower f = ...; // obtain your follower
  MessageMetric<Integer, LogWatch> m = f.startMeasuring(messageCounter, "Some Metric ID");
  Integer messageCount = m.getValue(); // should be zero, unless any messages arrived in the meantime

Notice the “Some Metric ID”? You can use this later to retrieve your metric instance using Follower.getMetric(String) method, if you ever need it. Oh and you can also use expectations on metrics.

Handing metrics down

Metrics can be used on all kinds of followers and also on LogWatch. However, there is something special about LogWatch, and that is its support for handing metrics down.

Measures registered through the LogWatch.startHandingDown(MessageMeasure, String) method will be handed down to any follower that is subsequently started from the same LogWatch. You can use this to have a different instance of your message counter from above for every follower that you create. This instance can be retrieved from the follower by using the textual ID that you provided to the LogWatch during registration.

When you no longer want future followers to measure this particular kind of data, simply call LogWatch.stopHandingDown(String) with the textual ID you provided originally. Be aware that this will not in any way affect the followers and metrics that already exist.