avast/metrics

Java/Scala library defining API for metrics publishing

Metrics

Java/Scala library defining API for metrics publishing. Implementation for Dropwizard Metrics is provided.
The library is incubating and there are some planned improvements. There can be some breaking changes in following major releases.

Introduction

Library for application monitoring. It's abstraction of metrics inspired by Dropwizard Metrics.

Main advantages of this library:

1. Universal abstraction with misc. implementations
2. Support of multiple exports at once (MultiMonitor)
3. Scala API
4. Scala Effect API (cats-effect 2 and 3)

The entry-point into the library is the interface Monitor. Your classes need to get an instance of a monitor which they can use to construct different metrics, e.g. meters, timers or histograms. Instances of the individuals metrics can be used to monitor your application.

Currently there are multiple implementations/exports:

• JMX (+ Avast specific format of export jmx-avast)
• Graphite
• StatsD
• Formatting to string in configurable formats, e.g. for serving via HTTP server

There is Scala API available in metrics-scala. See the example below.

Adding to project

The library is published to Bintray. Example usage of the StatsD in Gradle project:

repositories {
    jcenter()
}
dependencies {
    compile "com.avast.metrics:metrics-statsd:$versionHere"
}

Naming of Monitors

Each monitor can be named several times which creates a hierarchy of names for the final metric.

Naming the monitors is very important! Your metrics will be wrong if you give the same metric name to two unrelated metrics in different components. The Monitor behaves like a registry so it creates each metric just once and returns it if asked again for the same name. All your components should receive an instance of Monitor that was properly named for that particular component.

import com.avast.metrics.api.*;
import com.avast.metrics.dropwizard.*;

public class Handler {

    private final Meter requests;

    public Handler(Monitor monitor) {
        this.requests = monitor.newMeter("requests");
    }

    public void handle(String request) {
        requests.mark();
        ...
    }
}

Monitor monitor = null; // TODO specific monitor
Handler handler = new Handler(monitor.named("Handler1"));

Scala API

An easy-to-use Scala API is available in scala-api module. Wrap the Java Monitor by scalaapi.Monitor to use the Scala version.

import com.avast.metrics.scalaapi.Monitor
import com.avast.metrics.dropwizard.JmxMetricsMonitor

val javaMonitor = getJavaMonitor()
val scalaMonitor = Monitor(javaMonitor)

Scala Per-key API

Adds support for easier creating of counters and timers per some user given key.

val monitor = Monitor(new JmxMetricsMonitor("com.avast.some.app"))

val perPartnerRequestCounter = monitor.perKey.counter("requestPerVendor")

val x = perPartnerRequestCounter.forKey("a")
val a = perPartnerRequestCounter.forKey("b")

x.inc()
a.inc()

Scala Effect API

An easy-to-use Scala Effect API is available in scala-effect-api module. Wrap the Java Monitor by scalaeffectapi.Monitor to use the Cats-Effect version.

import com.avast.metrics.scalaeffectapi.Monitor
import com.avast.metrics.dropwizard.JmxMetricsMonitor

val javaMonitor = getJavaMonitor()
val scalaEffectMonitor: Monitor[F]  = Monitor.wrapJava(javaMonitor)

See example in tests.

Unit Testing

There is a singleton NoOpMonitor.INSTANCE in the metrics-api submodule that can be used in tests.
There are also available Monitor.noOp for Scala API and Scala Effect API.

Disabling JMX

Sometimes you want to globally disable JMX monitoring on the server. You can do that by setting system property avastMetricsDisableJmx=true. To do that from bash, you can use:

 java -jar -DavastMetricsDisableJmx="true" program.jar

Any value that is not true will be ignored.

metrics's Issues

Fix JDK11 build

After migration to build using JDK11 (required by TravisCI), we are getting this error:

[error] /home/travis/build/avast/metrics/core/src/main/java/com/avast/metrics/core/jvm/JvmMetrics.java:7:1: package sun.management is not visible
[error]   (package sun.management is declared in module java.management, which does not export it to the unnamed module)
[error] import sun.management.ManagementFactoryHelper;

I tried to solve it using this line of code but it didn't help so a need of an sbt guru is probably required.

javaOptions ++= Seq("--add-exports", "java.management/sun.management=ALL-UNNAMED"),

Update StatsD exaples to not to use deprecated methods

Now, the examples are using constructor (string, int, string`) that is marked as deprecated.

Please update these examples so we will know how to use it properly.

Thanks!

Sampling in statsd implementation

If some metric is updated very frequently, you can easily overload the statsd server. So it would be useful to have support for sampling in the statsd implementation.

Not sure, how it should be configured. E.g. we could specify sampling rate for all the metrics globally - it would be very straightforward.