Package io.vertx.ext.dropwizard

= Metrics This project implements the Vert.x Metrics Service Provider Interface (SPI) reporting metrics to the https://github.com/dropwizard/metrics[Dropwizard metrics] library.

See: Description

Interface Summary

Interface	Description
MetricsService	The metrics service mainly allows to return a snapshot of measured objects.

Class Summary

Class	Description
DropwizardMetricsOptions	Vert.x Dropwizard metrics configuration.
Match	A match for a value.
ScheduledMetricsConsumer	TODO - support listening to more than one Measured
ThroughputMeter	A throughput metric, wraps a Meter object to provide a one second instant throughput value returned by ThroughputMeter.getValue().
ThroughputTimer	A throughput metric, wraps a Meter object to provide a one second instant throughput value returned by ThroughputTimer.getValue().

Enum Summary

Enum	Description
MatchType	The type of match.

Package io.vertx.ext.dropwizard Description

= Metrics This project implements the Vert.x Metrics Service Provider Interface (SPI) reporting metrics to the https://github.com/dropwizard/metrics[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`): [source,xml,subs="+attributes"] ---- ${maven.groupId} ${maven.artifactId} ${maven.version} ---- * Gradle (in your `build.gradle` file): [source,groovy,subs="+attributes"] ---- compile ${maven.groupId}:${maven.artifactId}:${maven.version} ---- Then when you create vertx enable metrics using the DropwizardMetricsOptions: [source,$lang] ---- examples.MetricsExamples#setup() ---- You can also enable JMX: [source,$lang] ---- examples.MetricsExamples#setupJMX() ---- To see details about JMX see the <> 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 <> to use. The vertx.metrics.options.jmxEnabled and vertx.metrics.options.jmxDomain configures the <> 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 `baseName` + `.` + `metricName` from Vertx: [source,$lang] ---- examples.MetricsExamples#naming1 ---- or from the measured component itself using just the metric name: [source,$lang] ---- examples.MetricsExamples#naming2 ---- See more examples below on how to retrieve/use metrics for a specific component. Metrics names can also be listed: [source,$lang] ---- examples.MetricsExamples#naming3 ---- === 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: [source,$lang] ---- examples.MetricsExamples#example1 ---- NOTE: For details on the actual contents of the data (the actual metric) represented by the JsonObject consult the implementation documentation like https://github.com/vert-x3/vertx-metrics[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. [source,$lang] ---- examples.MetricsExamples#example2 ---- Metrics can also be retrieved using a base name: [source,$lang] ---- examples.MetricsExamples#example3 ---- == Data Below is how each dropwizard metric is represented in JSON. Please refer to the https://github.com/dropwizard/metrics[Dropwizard metrics] documentation for detailed information on each metric. [[gauge]] === Gauge [source,javascript] ---- { "type" : "gauge", "value" : value // any json value } ---- [[counter]] === Counter [source,$lang] ---- { "type" : "counter", "count" : 1 // number } ---- [[histogram]] === Histogram [source,javascript] ---- { "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]] === Meter [source,$lang] ---- { "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 } ---- [[throughput_meter]] === ThroughputMeter Extends a <> to provide an instant throughput. [source,$lang] ---- { "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]] === Timer A timer is basically a combination of Histogram + Meter. [source,$lang] ---- { "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]] === Throughput Timer Extends a <> to provide an instant throughput metric. [source,$lang] ---- { "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 <> of the number of threads in the event loop pool * `vertx.worker-pool-size` - A <> of the number of threads in the worker pool * `vertx.cluster-host` - A <> of the cluster-host setting * `vertx.cluster-port` - A <> of the cluster-port setting * `vertx.verticles` - A <> of the number of verticles currently deployed * `vertx.verticles.` - A <> of the number of deployment of a particular verticle === Event bus metrics Base name: `vertx.eventbus` * `handlers` - A <> of the number of event bus handlers * `handlers.myaddress` - A <> representing the rate of which messages are being received for the _myaddress_ handler * `messages.bytes-read` - A <> of the number of bytes read when receiving remote messages * `messages.bytes-written` - A <> of the number of bytes written when sending remote messages * `messages.pending` - A <> of the number of messages received but not yet processed by an handler * `messages.pending-local` - A <> of the number of messages locally received but not yet processed by an handler * `messages.pending-remote` - A <> of the number of messages remotely received but not yet processed by an handler * `messages.received` - A <> representing the rate of which messages are being received * `messages.received-local` - A <> representing the rate of which local messages are being received * `messages.received-remote` - A <> representing the rate of which remote messages are being received * `messages.delivered` - A <> representing the rate of which messages are being delivered to an handler * `messages.delivered-local` - A <> representing the rate of which local messages are being delivered to an handler * `messages.delivered-remote` - A <> representing the rate of which remote messages are being delivered to an handler * `messages.sent` - A <> representing the rate of which messages are being sent * `messages.sent-local` - A <> representing the rate of which messages are being sent locally * `messages.sent-remote` - A <> representing the rate of which messages are being sent remotely * `messages.published` - A <> representing the rate of which messages are being published * `messages.published-local` - A <> representing the rate of which messages are being published locally * `messages.published-remote` - A <> representing the rate of which messages are being published remotely * `messages.reply-failures` - A <> 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: [source,$lang] ---- examples.MetricsExamples#setupMonitoredHandlers() ---- WARNING: if you use regex match, a wrong regex can potentially match a lot of handlers. [[http-server-metrics]] === Http server metrics Base name: `vertx.http.servers.:` Http server includes all the metrics of a <> plus the following: * `requests` - A <> of a request and the rate of it's occurrence * `-requests` - A <> of a specific http method request and the rate of it's occurrence ** Examples: `get-requests`, `post-requests` * `-requests./` - A <> 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 <> of the 1xx response code * `responses-2xx` - A <> of the 2xx response code * `responses-3xx` - A <> of the 3xx response code * `responses-4xx` - A <> of the 4xx response code * `responses-5xx` - A <> of the 5xx response code * `open-websockets` - A <> of the number of open web socket connections * `open-websockets.` - A <> 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: [source,$lang] ---- examples.MetricsExamples#setupMonitoredUris() ---- *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.@` Http client includes all the metrics of a <> plus the following: * `connections.max-pool-size` - A <> of the max connection pool size * `connections.pool-ratio` - A ratio <> of the open connections / max connection pool size * `responses-1xx` - A <> of the 1xx response code * `responses-2xx` - A <> of the 2xx response code * `responses-3xx` - A <> of the 3xx response code * `responses-4xx` - A <> of the 4xx response code * `responses-5xx` - A <> of the 5xx response code [[net-server-metrics]] === Net server metrics Base name: `vertx.net.servers.:` * `open-netsockets` - A <> of the number of open net socket connections * `open-netsockets.` - A <> of the number of open net socket connections for a particular remote host * `connections` - A <> of a connection and the rate of it's occurrence * `exceptions` - A <> of the number of exceptions * `bytes-read` - A <> of the number of bytes read. * `bytes-written` - A <> of the number of bytes written. === Net client metrics Base name: `vertx.net.clients.@` Net client includes all the metrics of a <> === Datagram socket metrics Base name: `vertx.datagram` * `sockets` - A <> of the number of datagram sockets * `exceptions` - A <> of the number of exceptions * `bytes-written` - A <> of the number of bytes written. * `:.bytes-read` - A <> of the number of bytes read. ** This metric will only be available if the datagram socket is listening [[jmx]] == JMX JMX is disabled by default. If you want JMX, then you need to enabled that: [source,$lang] ---- examples.MetricsExamples#setupJMX() ---- 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: [source,$lang] ---- examples.MetricsExamples#setupJMXWithDomain() ---- == 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 http://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html[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* [[dropwizard-registry]] == Accessing Dropwizard Registry When configuring the metrics service, an optional registry name can be specified for registering the underlying https://dropwizard.github.io/metrics/3.1.0/getting-started/#the-registry[Dropwizard Registry] in the the https://dropwizard.github.io/metrics/3.1.0/apidocs/com/codahale/metrics/SharedMetricRegistries.html[Dropwizard Shared Registry] so you can retrieve this registry and use according to your needs. [source,java] ---- 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 ----