Basics

Gauges

Gauges measure discrete values at the time they are sampled. These are useful for measuring queue depths and pool sizes.

// scala
import java.util.ArrayBlockingQueue

val aQueue = new ArrayBlockingQueue[Job]()

val queueSize = statsReceiver.addGauge("queue_size") {
  aQueue.size
}

// java
import com.twitter.finagle.stats.Gauge;
import java.util.ArrayBlockingQueue;

ArrayBlockingQueue<Job> aQueue =
  new ArrayBlockingQueue<Job>();

Gauge queueSize = StatsReceivers.addGauge(
  statsReceiver,
  new Callable<Float>() {
    @Override public Float call() { return aQueue.size(); }
  },
  "queue_size"
);

Counters

Counters are used to, well, count how often something happens. Common examples include the number of requests dispatched and failure counts.

// scala
val numRequests = statsReceiver.counter("num_requests")

numRequests.incr()

// java
import com.twitter.finagle.stats.Counter;

Counter numRequests =
  statsReceiver.counter(statsReceiver, "num_requests");

numRequests.incr();

Stats

Stats provide a distribution of values that are seen, including percentiles, averages and maximums. Stats are quite useful for measuring the n-th percentiles for latency of requests or capturing the distribution of work batches.

// scala
import com.twitter.finagle.stats.Stat
import java.util.concurrent.TimeUnit

val latency = statsReceiver.stat("latency_ms")

Stat.time(latency, TimeUnit.MILLISECONDS) {
  twiddleBits();
}

// java
import com.twitter.finagle.stats.Stat;
import com.twitter.finagle.stats.JStat;
import java.util.concurrent.TimeUnit;

Stat latency = statsReceiver.stat(statsReceiver, "latency_ms");

JStat.time(
  latency,
  new Callable<Void>() {
    @Override public void call() { twiddleBits(); }
  },
  TimeUnit.MILLISECONDS
);

Verbosity Levels

Each metric created via a StatsReceiver has a verbosity level (i.e., “debug” or “default”) attached to it. Distinguishing verbosity levels for metrics is optional and is up to a concrete implementation. Doing this, however, helps to separate debug metrics (only helpful in troubleshooting) from their operationally-required counterparts (provide visibility into a healthy process) thus potentially reducing the observability cost.

Note

Unless an explicit Verbosity is passed, Verbosity.Default is used.

// scala
import com.twitter.finagle.stats.Verbosity

val someDebugEvent = statsReceiver.counter(Verbosity.Debug, "some_debug_event")

// java
import java.util.concurrent.Counter;
import java.util.concurrent.Verbosity;

Counter someDebugEvent = statsReceiver.counter(Verbosity.Debug(), "some_debug_event")