# Metrics

This project implements the Vert.x Metrics Service Provider Interface (SPI) reporting metrics to the Dropwizard metrics library.

## Features

A fairly simple API to retrieve metrics via the `Measured` interface which is implemented by various Vert.x components like `HttpServer`, `NetServer`, and even `Vertx` itself.

Confiugrable JMX reporting based on Dropwizard implementation, exposing Vert.x as JMX MBeans.

## Getting started

To enable metrics, add the following dependency to the dependencies section of your build descriptor:

- Maven (in your `pom.xml`):

    <dependency>
      <groupId>io.vertx</groupId>
      <artifactId>vertx-dropwizard-metrics</artifactId>
      <version>3.1.0</version>
    </dependency>

- Gradle (in your `build.gradle` file):

    compile io.vertx:vertx-dropwizard-metrics:3.1.0

Then when you create vertx enable metrics using the `DropwizardMetricsOptions`:

    import io.vertx.groovy.core.Vertx
    def vertx = Vertx.vertx([
      metricsOptions:[
        enabled:true
      ]
    ])

You can also enable JMX:

    import io.vertx.groovy.core.Vertx
    def vertx = Vertx.vertx([
      metricsOptions:[
        jmxEnabled:true
      ]
    ])

To see details about JMX see the JMX section at the bottom.

## Command line activation

When running Vert.x from the command line interface, metrics can be activated via JVM system properties. System properties beginning with vertx.metrics.options. are transmitted to the metrics options.

The vertx.metrics.options.enabled is a standard Vert.x Core option for enabling the metrics implementations, this options must be set to `true`.

The `vertx.metrics.options.registryName` configures the Dropwizard Registry to use.

The `vertx.metrics.options.jmxEnabled` and `vertx.metrics.options.jmxDomain` configures the JMX registration.

The `vertx.metrics.options.configPath` option allows to reconfigure the metrics from a property file.

## Metrics service

While Vert.x core defines an SPI for reporting metrics (implemented for instance in this project), it does not define an API for retrieving metrics (because some metrics collectors just do reporting and nothing more).

The `MetricsService` provides an API in front of the Dropwizard Registry to get metrics data snapshots.

### Naming

Each measured component listed below (except for Vertx) will have a base name associated with it. Each metric can be retrieved by providing the fully qualified name <fqn> `baseName` + `.` + `metricName` from Vertx:

    def metrics = metricsService.getMetricsSnapshot(vertx)
    metrics.vertx.eventbus.handlers

or from the measured component itself using just the metric name:

    def eventBus = vertx.eventBus()
    def metrics = metricsService.getMetricsSnapshot(eventBus)
    metrics.handlers

See more examples below on how to retrieve/use metrics for a specific component.

Metrics names can also be listed:

    def metricsNames = metricsService.metricsNames()
    metricsNames.each { metricsName ->
      println("Known metrics name ${metricsName}")
    }

### Retrieving metrics

Once enabled, the `MetricsService` allows to retrieve metrics snapshots from any `Measured` object which provides a map of the metric name to the data, represented by a `JsonObject`. So for example if we were to print out all metrics for a particular Vert.x instance:

    import io.vertx.groovy.ext.dropwizard.MetricsService
    def metricsService = MetricsService.create(vertx)
    def metrics = metricsService.getMetricsSnapshot(vertx)
    println(metrics)

Note | For details on the actual contents of the data (the actual metric) represented by the `JsonObject` consult the implementation documentation like vertx-metrics

Often it is desired that you only want to capture specific metrics for a particular component, like an http server without having to know the details of the naming scheme of every metric (something which is left to the implementers of the SPI).

Since `HttpServer` implements `Measured`, you can easily grab all metrics that are specific for that particular http server.

    import io.vertx.groovy.ext.dropwizard.MetricsService
    def metricsService = MetricsService.create(vertx)
    def server = vertx.createHttpServer()
    // set up server
    def metrics = metricsService.getMetricsSnapshot(server)

Metrics can also be retrieved using a base name:

    import io.vertx.groovy.ext.dropwizard.MetricsService
    def metricsService = MetricsService.create(vertx)
    def metrics = metricsService.getMetricsSnapshot("vertx.eventbus.message")

## Data

Below is how each dropwizard metric is represented in JSON. Please refer to the Dropwizard metrics documentation for detailed information on each metric.

### Gauge

    {
      "type"  : "gauge",
      "value" : value // any json value
    }

### Counter

    {
      "type"  : "counter",
      "count" : 1 // number
    }

### Histogram

    {
      "type"   : "histogram",
      "count"  : 1 // long
      "min"    : 1 // long
      "max"    : 1 // long
      "mean"   : 1.0 // double
      "stddev" : 1.0 // double
      "median" : 1.0 // double
      "75%"    : 1.0 // double
      "95%"    : 1.0 // double
      "98%"    : 1.0 // double
      "99%"    : 1.0 // double
      "99.9%"  : 1.0 // double
    }

### Meter

    {
      "type"              : "meter",
      "count"             : 1 // long
      "meanRate"          : 1.0 // double
      "oneMinuteRate"     : 1.0 // double
      "fiveMinuteRate"    : 1.0 // double
      "fifteenMinuteRate" : 1.0 // double
      "rate"              : "events/second" // string representing rate
    }

### ThroughputMeter

Extends a Meter to provide an instant throughput.

    {
      "type"              : "meter",
      "count"             : 40 // long
      "meanRate"          : 2.0 // double
      "oneSecondRate"     : 3 // long - number of occurence for the last second
      "oneMinuteRate"     : 1.0 // double
      "fiveMinuteRate"    : 1.0 // double
      "fifteenMinuteRate" : 1.0 // double
      "rate"              : "events/second" // string representing rate
    }

### Timer

A timer is basically a combination of Histogram + Meter.

    {
      "type": "timer",

      // histogram data
      "count"  : 1 // long
      "min"    : 1 // long
      "max"    : 1 // long
      "mean"   : 1.0 // double
      "stddev" : 1.0 // double
      "median" : 1.0 // double
      "75%"    : 1.0 // double
      "95%"    : 1.0 // double
      "98%"    : 1.0 // double
      "99%"    : 1.0 // double
      "99.9%"  : 1.0 // double

      // meter data
      "meanRate"          : 1.0 // double
      "oneMinuteRate"     : 1.0 // double
      "fiveMinuteRate"    : 1.0 // double
      "fifteenMinuteRate" : 1.0 // double
      "rate"              : "events/second" // string representing rate
    }

### Throughput Timer

Extends a Timer to provide an instant throughput metric.

    {
      "type": "timer",

      // histogram data
      "count"      : 1 // long
      "min"        : 1 // long
      "max"        : 1 // long
      "mean"       : 1.0 // double
      "stddev"     : 1.0 // double
      "median"     : 1.0 // double
      "75%"        : 1.0 // double
      "95%"        : 1.0 // double
      "98%"        : 1.0 // double
      "99%"        : 1.0 // double
      "99.9%"      : 1.0 // double

      // meter data
      "meanRate"          : 1.0 // double
      "oneSecondRate"     : 3 // long - number of occurence for the last second
      "oneMinuteRate"     : 1.0 // double
      "fiveMinuteRate"    : 1.0 // double
      "fifteenMinuteRate" : 1.0 // double
      "rate"              : "events/second" // string representing rate
    }

## The metrics

The following metrics are currently provided.

### Vert.x metrics

The following metrics are provided:

- `vertx.event-loop-size` - A Gauge of the number of threads in the event loop pool

- `vertx.worker-pool-size` - A Gauge of the number of threads in the worker pool

- `vertx.cluster-host` - A Gauge of the cluster-host setting

- `vertx.cluster-port` - A Gauge of the cluster-port setting

- `vertx.verticles` - A Counter of the number of verticles currently deployed

- `vertx.verticles.<verticle-name>` - A Counter of the number of deployment of a particular verticle

### Event bus metrics

Base name: `vertx.eventbus`

- `handlers` - A Counter of the number of event bus handlers

- `handlers.myaddress` - A Timer representing the rate of which messages are being received for the myaddress handler

- `messages.bytes-read` - A Meter of the number of bytes read when receiving remote messages

- `messages.bytes-written` - A Meter of the number of bytes written when sending remote messages

- `messages.pending` - A Counter of the number of messages received but not yet processed by an handler

- `messages.pending-local` - A Counter of the number of messages locally received but not yet processed by an handler

- `messages.pending-remote` - A Counter of the number of messages remotely received but not yet processed by an handler

- `messages.received` - A ThroughputMeter representing the rate of which messages are being received

- `messages.received-local` - A ThroughputMeter representing the rate of which local messages are being received

- `messages.received-remote` - A ThroughputMeter representing the rate of which remote messages are being received

- `messages.delivered` - A [throughpu_metert] representing the rate of which messages are being delivered to an handler

- `messages.delivered-local` - A ThroughputMeter representing the rate of which local messages are being delivered to an handler

- `messages.delivered-remote` - A ThroughputMeter representing the rate of which remote messages are being delivered to an handler

- `messages.sent` - A [throughput_metert] representing the rate of which messages are being sent

- `messages.sent-local` - A ThroughputMeter representing the rate of which messages are being sent locally

- `messages.sent-remote` - A ThroughputMeter representing the rate of which messages are being sent remotely

- `messages.published` - A ThroughputMeter representing the rate of which messages are being published

- `messages.published-local` - A ThroughputMeter representing the rate of which messages are being published locally

- `messages.published-remote` - A ThroughputMeter representing the rate of which messages are being published remotely

- `messages.reply-failures` - A Meter representing the rate of reply failures

The monitored event bus handlers is configurable via a match performed on the handler registration address. Vert.x can have potentially a huge amount of registered event bus, therefore the only good default for this setting is to monitor zero handlers.

The monitored handlers can be configured in the `DropwizardMetricsOptions` via a specific address match or a regex match:

    import io.vertx.ext.dropwizard.MatchType
    import io.vertx.groovy.core.Vertx
    def vertx = Vertx.vertx([
      metricsOptions:[
        enabled:true,
        monitoredEventBusHandlers:[
          [
            value:"some-address"
          ],
          [
            value:"business-.*",
            type:MatchType.REGEX
          ]
        ]
      ]
    ])

Warning | if you use regex match, a wrong regex can potentially match a lot of handlers.

### Http server metrics

Base name: `vertx.http.servers.<host>:<port>`

Http server includes all the metrics of a Net Server plus the following:

- `requests` - A Throughput Timer of a request and the rate of it’s occurrence

- `<http-method>-requests` - A Throughput Timer of a specific http method request and the rate of it’s occurrence

  - Examples: `get-requests`, `post-requests`

- `<http-method>-requests./<uri>` - A Throughput Timer of a specific http method & URI request and the rate of it’s occurrence

  - Examples: `get-requests./some/uri`, `post-requests./some/uri?foo=bar`

- `responses-1xx` - A ThroughputMeter of the 1xx response code

- `responses-2xx` - A ThroughputMeter of the 2xx response code

- `responses-3xx` - A ThroughputMeter of the 3xx response code

- `responses-4xx` - A ThroughputMeter of the 4xx response code

- `responses-5xx` - A ThroughputMeter of the 5xx response code

- `open-websockets` - A Counter of the number of open web socket connections

- `open-websockets.<remote-host>` - A Counter of the number of open web socket connections for a particular remote host

Http URI metrics must be explicitely configured in the options either by exact match or regex match:

    import io.vertx.ext.dropwizard.MatchType
    import io.vertx.groovy.core.Vertx
    def vertx = Vertx.vertx([
      metricsOptions:[
        enabled:true,
        monitoredHttpServerUris:[
          [
            value:"/"
          ],
          [
            value:"/foo/.*",
            type:MatchType.REGEX
          ]
        ]
      ]
    ])

For `bytes-read` and `bytes-written` the bytes represent the body of the request/response, so headers, etc are ignored.

### Http client metrics

Base name: `vertx.http.clients.@<id>`

Http client includes all the metrics of a Http Server plus the following:

- `connections.max-pool-size` - A Gauge of the max connection pool size

- `connections.pool-ratio` - A ratio Gauge of the open connections / max connection pool size

- `responses-1xx` - A Meter of the 1xx response code

- `responses-2xx` - A Meter of the 2xx response code

- `responses-3xx` - A Meter of the 3xx response code

- `responses-4xx` - A Meter of the 4xx response code

- `responses-5xx` - A Meter of the 5xx response code

### Net server metrics

Base name: `vertx.net.servers.<host>:<port>`

- `open-netsockets` - A Counter of the number of open net socket connections

- `open-netsockets.<remote-host>` - A Counter of the number of open net socket connections for a particular remote host

- `connections` - A Timer of a connection and the rate of it’s occurrence

- `exceptions` - A Counter of the number of exceptions

- `bytes-read` - A Histogram of the number of bytes read.

- `bytes-written` - A Histogram of the number of bytes written.

### Net client metrics

Base name: `vertx.net.clients.@<id>`

Net client includes all the metrics of a Net Server

### Datagram socket metrics

Base name: `vertx.datagram`

- `sockets` - A Counter of the number of datagram sockets

- `exceptions` - A Counter of the number of exceptions

- `bytes-written` - A Histogram of the number of bytes written.

- `<host>:<port>.bytes-read` - A Histogram of the number of bytes read.

  - This metric will only be available if the datagram socket is listening

## JMX

JMX is disabled by default.

If you want JMX, then you need to enabled that:

    import io.vertx.groovy.core.Vertx
    def vertx = Vertx.vertx([
      metricsOptions:[
        jmxEnabled:true
      ]
    ])

If running Vert.x from the command line you can enable metrics and JMX by uncommented the JMX_OPTS line in the `vertx` or `vertx.bat` script:

    JMX_OPTS="-Dcom.sun.management.jmxremote -Dvertx.options.jmxEnabled=true"

You can configure the domain under which the MBeans will be created:

    import io.vertx.groovy.core.Vertx
    def vertx = Vertx.vertx([
      metricsOptions:[
        jmxEnabled:true,
        jmxDomain:"mydomain"
      ]
    ])

## Enabling remote JMX

If you want the metrics to be exposed remotely over JMX, then you need to set, at minimum the following system property:

`com.sun.management.jmxremote`

If running from the command line this can be done by editing the `vertx` or `vertx.bat` and uncommenting the `JMX_OPTS` line.

Please see the Oracle JMX documentation for more information on configuring JMX

If running Vert.x on a public server please be careful about exposing remote JMX access

## Accessing Dropwizard Registry

When configuring the metrics service, an optional registry name can be specified for registering the underlying Dropwizard Registry in the the Dropwizard Shared Registry so you can retrieve this registry and use according to your needs.

    VertxOptions options = new VertxOptions().setMetricsOptions(
      new MetricsServiceOptions().setEnabled(true).setRegistryName("the_name")
    );
    Vertx vertx = Vertx.vertxt(options);

    // Get the registry
    MetricRegistry registry = SharedMetricRegistries.getOrCreate("the_name");

    // Do whatever you need with the registry