This project is an implementation of the Vert.x Metrics Service Provider Interface (SPI): metrics built from Vert.x events will be sent to Hawkular, an open source monitoring and management solution.
Features
-
Vert.x core tools monitoring: TCP/HTTP client and servers,
DatagramSocket,EventBusand handlers -
User defined metrics via an
EventBusbridge.
Prerequisites
Follow the instructions to get Hawkular up and running.
|
Note
|
You can use a standalone Hawkular Metrics server as well. |
Getting started
The vertx-hawkular-metrics module must be present in the classpath.
Maven users should add this to their project POM file:
<dependency>
<groupId>io.vertx</groupId>
<artifactId>vertx-hawkular-metrics</artifactId>
<version>3.5.2.CR2</version>
</dependency>
And Gradle users, to their build file:
compile 'io.vertx:vertx-hawkular-metrics:3.5.2.CR2'
Vert.x does not enable SPI implementations by default. You must enable metric collection in the Vert.x options:
var vertx = Vertx.vertx(VertxOptions(
metricsOptions = VertxHawkularOptions(
enabled = true)))
Configuration
Remote Hawkular server
By default, vertx-hawkular-metrics sends metrics to a Hawkular server listening on localhost port 8080.
But in production, the Hawkular server will likely run on a separate machine:
var vertx = Vertx.vertx(VertxOptions(
metricsOptions = VertxHawkularOptions(
enabled = true,
host = "hawkular.example.com",
port = 8080)))
Tenant selection
Hawkular Metrics is a multi-tenant solution, and vertx-hawkular-metrics can send metrics for a tenant other than default:
var vertx = Vertx.vertx(VertxOptions(
metricsOptions = VertxHawkularOptions(
enabled = true,
tenant = "sales-department")))
Connecting to a Hawkular server
Requests sent to a Hawkular server must be authenticated and tenant must be set to hawkular:
var vertx = Vertx.vertx(VertxOptions(
metricsOptions = VertxHawkularOptions(
enabled = true,
tenant = "hawkular",
authenticationOptions = AuthenticationOptions(
enabled = true,
id = "username",
secret = "password"))))
Openshift Metrics token authentication
When working with Openshift’s internal Metrics server, you can configure token authentication with a custom HTTP header:
var vertx = Vertx.vertx(VertxOptions(
metricsOptions = VertxHawkularOptions(
enabled = true,
tenant = "my-namespace",
httpHeaders = json {
obj("Authorization" to "Bearer xkjdksf9890-shjkjhkjlkjlk")
})))
HTTPS and other HTTP related options
vertx-hawkular-metrics communicates with the Hawkular server over HTTP. In order to communicate over HTTPS, set the
ssl flag to true:
var vertx = Vertx.vertx(VertxOptions(
metricsOptions = VertxHawkularOptions(
enabled = true,
host = "hawkular.example.com",
port = 443,
httpOptions = HttpClientOptions(
ssl = true))))
|
Note
|
The usual HttpClientOptions properties can be used for SSL setup or client
tuning.
|
Metric tags
Tags can be applied to metrics:
var vertx = Vertx.vertx(VertxOptions(
metricsOptions = VertxHawkularOptions(
enabled = true,
tags = json {
obj(
"dc" to "mars01",
"rack" to "web-paca",
"host" to "host13"
)
})))
vertx-hawkular-metrics maintains a LRU cache of tagged metrics to avoid repeating tagging requests.
The cache size can be configured and defaults to 4096 metric names.
It is also possible to apply tags to a specific set of metrics defined via exact match or regex match:
var vertx = Vertx.vertx(VertxOptions(
metricsOptions = VertxHawkularOptions(
enabled = true,
metricTagsMatches = listOf(MetricTagsMatch(
value = "myapp.foo.my-metric",
tags = json {
obj("myapp" to "foo")
}), MetricTagsMatch(
type = MatchType.REGEX,
value = ".*\\.foo\\.*",
tags = json {
obj("myapp" to "foo")
})))))
|
Warning
|
If you use regex match, a wrong regex can potentially match a lot of metrics. |
|
Note
|
When evaluating tags to apply, metric specific tags have higher priority than global tags. In other words, a metric specific tag may overwrite a global tag. |
Please refer to VertxHawkularOptions for an exhaustive list of options.
Vert.x core tools metrics
This section lists all the metrics generated by monitoring the Vert.x core tools.
Net Client
| Metric type | Metric name | Description |
|---|---|---|
Gauge |
|
Number of connections to the remote host currently opened. |
Counter |
|
Total number of bytes received from the remote host. |
Counter |
|
Total number of bytes sent to the remote host. |
Counter |
|
Total number of errors. |
HTTP Client
| Metric type | Metric name | Description |
|---|---|---|
Gauge |
|
Number of connections to the remote host currently opened. |
Counter |
|
Total number of bytes received from the remote host. |
Counter |
|
Total number of bytes sent to the remote host. |
Counter |
|
Total number of errors. |
Gauge |
|
Number of requests waiting for a response. |
Counter |
|
Total number of requests sent. |
Counter |
|
Cumulated response time. |
Gauge |
|
Number of websockets currently opened. |
Datagram socket
| Metric type | Metric name | Description |
|---|---|---|
Counter |
|
Total number of bytes received on the |
Counter |
|
Total number of bytes sent to the remote host. |
Counter |
|
Total number of errors. |
Net Server
| Metric type | Metric name | Description |
|---|---|---|
Gauge |
|
Number of opened connections to the Net Server listening on the |
Counter |
|
Total number of bytes received by the Net Server listening on the |
Counter |
|
Total number of bytes sent to the Net Server listening on the |
Counter |
|
Total number of errors. |
HTTP Server
| Metric type | Metric name | Description |
|---|---|---|
Gauge |
|
Number of opened connections to the HTTP Server listening on the |
Counter |
|
Total number of bytes received by the HTTP Server listening on the |
Counter |
|
Total number of bytes sent to the HTTP Server listening on the |
Counter |
|
Total number of errors. |
Gauge |
|
Number of requests being processed. |
Counter |
|
Total number of requests processed. |
Counter |
|
Cumulated request processing time. |
Gauge |
|
Number of websockets currently opened. |
Event Bus
| Metric type | Metric name | Description |
|---|---|---|
Gauge |
|
Number of event bus handlers. |
Counter |
|
Total number of errors. |
Counter |
|
Total number of bytes sent while sending messages to event bus cluster peers. |
Counter |
|
Total number of bytes received while reading messages from event bus cluster peers. |
Gauge |
|
Number of messages not processed yet. One message published will count for |
Gauge |
|
Like |
Gauge |
|
Like |
Counter |
|
Total number of messages published (publish / subscribe). |
Counter |
|
Like |
Counter |
|
Like |
Counter |
|
Total number of messages sent (point-to-point). |
Counter |
|
Like |
Counter |
|
Like |
Counter |
|
Total number of messages received. |
Counter |
|
Like |
Counter |
|
Like |
Counter |
|
Total number of messages delivered to handlers. |
Counter |
|
Like |
Counter |
|
Like |
Counter |
|
Total number of message reply failures. |
Counter |
|
Cumulated processing time for handlers listening to the |
Vert.x pool metrics
This section lists all the metrics generated by monitoring Vert.x pools.
There are two types currently supported:
-
worker (see
WorkerExecutor) -
datasource (created with Vert.x JDBC client)
|
Note
|
Vert.x creates two worker pools upfront, vert.x-worker-thread and vert.x-internal-blocking. |
All metrics are prefixed with <type>.<name>.. For example, worker.vert.x-internal-blocking..
| Metric type | Metric name | Description |
|---|---|---|
Counter |
|
Cumulated time waiting for a resource (queue time). |
Gauge |
|
Current number of elements waiting for a resource. |
Counter |
|
Total number of elements queued. |
Counter |
|
Cumulated time using a resource (i.e. processing time for worker pools). |
Gauge |
|
Current number of resources used. |
Counter |
|
Total number of elements done with the resource (i.e. total number of tasks executed for worker pools). |
Gauge |
|
Maximum pool size, only present if it could be determined. |
Gauge |
|
Pool usage ratio, only present if maximum pool size could be determined. |
Verticle metrics
| Metric type | Metric name | Description |
|---|---|---|
Gauge |
|
Number of verticle instances deployed. |
User defined metrics
Users can send their own metrics to the Hawkular server. In order to do so, the event bus metrics bridge must be enabled:
var vertx = Vertx.vertx(VertxOptions(
metricsOptions = VertxHawkularOptions(
enabled = true,
metricsBridgeEnabled = true)))
By default, the metrics bus handler is listening to the hawkular.metrics address. But the bridge address
can be configured:
var vertx = Vertx.vertx(VertxOptions(
metricsOptions = VertxHawkularOptions(
enabled = true,
metricsBridgeEnabled = true,
metricsBridgeAddress = "__hawkular_metrics")))
The metrics bridge handler expects messages in the JSON format. The JSON object must at least provide a metric
id and a numerical value:
var message = json {
obj(
"id" to "myapp.files.opened",
"value" to 7
)
}
vertx.eventBus().publish("hawkular.metrics", message)
The handler will assume the metric is a gauge and will assign a timestamp corresponding to the time when the message was processed.
If the metric is a counter or availability, or if you prefer explicit configuration, set the type and/or timestamp attributes:
var counterMetric = json {
obj(
"id" to "myapp.files.opened",
"type" to "counter",
"timestamp" to 189898098098908L,
"value" to 7
)
}
vertx.eventBus().publish("hawkular.metrics", counterMetric)
var availabilityMetric = json {
obj(
"id" to "myapp.mysubsystem.status",
"type" to "availability",
"value" to "up"
)
}
vertx.eventBus().publish("hawkular.metrics", availabilityMetric)
|
Note
|
Hawkular understands all timestamps as milliseconds since January 1, 1970, 00:00:00 UTC. |