Knot.x Dropwizard Metrics

This simple Knot.x module sends Vert.x Dropwizard metrics gathered by already registered Dropwizard Registry to the chosen Reporter.

• How does it work
• How to use
  • Prerequisites
  • Configuration
  • Running
• Dropwizard metrics tuning
  • Metrics Options
    • Monitoring EventBus handlers
    • Monitoring Http Server uris
    • Monitoring Http Cilent uris
    • Monitoring Http Cilent endpoints
• Reporters
  • Console
  • Logger
  • Graphite
• Creating a custom Reporter

How does it work

This module uses the Vert.x Dropwizard Metrics that implements the Vert.x Metrics Service Provider Interface (SPI) reporting metrics to the Dropwizard metrics library. The concept base on connecting to already existing Dropwizard Registry that collects the metrics. The registry is identified by the system property vertx.metrics.options.registryName. If the property is not set, the default name knotx-dropwizard-registry will be used. In the module configuration a Reporter can be configured to define metrics consumer endpoint.

For any details on metrics and Vert.x please refer to this article:

• https://vertx.io/docs/vertx-dropwizard-metrics/java/

How to use

Note: Knot.x Dropwizard Metrics does not have any runtime dependency on Knot.x. That means this module can be used on any Vert.x instance (including Knot.x of course :) ). However, project depends on the knotx-dependencies that defines Vert.x version used in this project.

Prerequisites

In order to use Knot.x Dropwizard Metrics in your Vert.x instance you need to have Vert.x metrics enabled and Dropwizard Registry created. The easiest way to do it is by passing the following commandline parameters when running an instance:

-Dvertx.metrics.options.enabled=true -Dvertx.metrics.options.registryName=my-knotx-registry

Note: If you are using Knot.x instance, the only thing you need to do is to uncomment METRICS_OPTS line in bin/knotx:

METRICS_OPTS="-Dvertx.metrics.options.enabled=true -Dvertx.metrics.options.registryName=knotx-dropwizard-registry"

Configuration

Two things needs to be configured in order to setup module properly:

• pollsPeriod - how often (milliseconds) should metrics be sent
• reporter - that defines a name of the reporter that factory (registered via Service Provider Interface (SPI)) provides and config that is passed to the reporter. See available reporters implementations for more details on available configuration options.

Sample configuration would look like this:

{
    pollsPeriod: 3000
    reporter {
      name: "console"
      config {
        # any config for the Console Reporter
      }
    }
}

Running

Knot.x Dropwizard Metrics Core contains a verticle io.knotx.metrics.DropwizardMetricsVerticle. It should be deployed on the running Vert.x instance together with its configuration.

If you are using Knot.x follow these steps:

1. Update the configration stores (usually conf/bootstrap.json) with new store for the this module:

 ...
    "stores": [
       ...
    
      {
        "type": "file",
        "format": "conf",
        "config": {
          "path": "${KNOTX_HOME}/conf/dropwizardMetrics.conf"
        }
      }
    ]
 ...

2. Create /conf/dropwizardMetrics.conf file, define a new module for Knot.x Dropwizard Metrics and pass the configuration to it:

modules {
  metrics = "io.knotx.metrics.DropwizardMetricsVerticle"
}

config.metrics {
  options.config {
    # module configuration here
  }
}

3. Add the proper dependencies for the metrics core and reporter that will be used to your Knot.x stack:

dependencies {
    // ...
    "dist"("io.knotx:knotx-dropwizard-core:version")
    "dist"("io.knotx:knotx-dropwizard-reporter-xxxxx:version")
}

4. Make sure you uncommented METRICS_OPTS line in bin/knotx.

Note: If your project was created using Knot.x Starter Kit you will have to copy bin/knotx file to your project (to knotx/conf/bin/knotx) to overwrite the default bin/knotx form the Knot.x Stack / Knot.x Docker image. Don't forget to set proper chmod after copying it.

Dropwizard metrics tuning

There is great number of Vert.x metrics gathered by Dropwizard:

• https://vertx.io/docs/vertx-dropwizard-metrics/java/#_the_metrics

Additionally some metrics can be tracked when configured.

Metrics Options

Additional options may be passed to the Dropwizard using Vert.x Dropwizard Options via JSON configuration file. In order to do that:

• create a metrics-options.json file
• pass additional parameter when starting instance -Dvertx.metrics.options.configPath=path-to/metrics-options.json

Note: The easiest way to configure these options with Knot.x is to create the configuration file in the conf directory, so that the path would be -Dvertx.metrics.options.configPath=conf/metrics-options.json.

Example metrics-options.json can look like this:

{
  "enabled": true,
  "monitoredEventBusHandlers": [],
  "monitoredHttpServerUris": [],
  "monitoredHttpClientUris": [],
  "monitoredHttpClientEndpoints": [],
  "baseName": "knotx"
}

Monitoring EventBus handlers

The list of <Matches> for monitored event bus handlers, e.g.

{
  "alias": "HandlebarsAction",
  "value": "knotx.knot.te.handlebars"
}

Monitoring Http Server uris

The list of <Matches> for monitored http server uris, e.g.

{
  "alias": "api-v1",
  "type": "REGEX",
  "value": ".*/api/v1/.*"
}

Monitoring Http Cilent uris

The list of <Matches> for monitored http client uris

{
  "alias": "Web API user",
  "type": "REGEX",
  "value": ".*/user.*"
}

Monitoring Http Cilent endpoints

The list of <Matches> for monitored http client endpoints

{
    "alias": "googleapis",
    "value": "www.googleapis.com:443"
}

Reporters

Reporters are implementations of Dropwizard's ScheduledReporter provided via the SPI using Factory that implements DropwizardMetricsReporterFactory from the api module. Below you will find the implementations delivered with this project.

Console

Uses ConsoleReporter which periodically reports all registered metrics to the console.

To use this reporter set: reporter.name = console.

Configuration

• rateUnit - string representation of the java.util.concurrent.TimeUnit value, rates will be converted to the given time unit (default SECONDS)
• durationUnit - string representation of the java.util.concurrent.TimeUnit value, durations will be converted to the given time unit (default MILLISECONDS)

Logger

Uses Slf4jReporter which periodically logs metrics to the metrics logger (you need to define that logger).

To use this reporter set: reporter.name = logger.

Configuration

• rateUnit - string representation of the java.util.concurrent.TimeUnit value, rates will be converted to the given time unit (default SECONDS)
• durationUnit - string representation of the java.util.concurrent.TimeUnit value, durations will be converted to the given time unit (default MILLISECONDS)
• loggingLevel - logging level used when reporting (default INFO)

Graphite

Uses GraphiteReporter which periodically sends metrics to the backend server using Graphite Protocol (it is supported by various back-ends like Carbon or InfuxDb).

To use this reporter set: reporter.name = graphite.

Prerequisites You need a running Graphite back-end where metrics can be sent. The easiest way to setup one would be docker:

• Graphite image,
• InfluxDb image.

Configuration

• rateUnit - string representation of the java.util.concurrent.TimeUnit value, rates will be converted to the given time unit (default SECONDS)
• durationUnit - string representation of the java.util.concurrent.TimeUnit value, durations will be converted to the given time unit (default MILLISECONDS)
• prefix - prefix all metric names with the given string
• graphite - JsonObject with address and port pointing to graphite back-end.

Creating a custom Reporter

To create a new Reporter available via SPI follow these instructions:

• Implement DropwizardMetricsReporterFactory
• add META-INF/services/io.knotx.metrics.reporter.DropwizardMetricsReporterFactory file to the resources that refers created factory in order to register it in the Service Provider