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.0</version>
</dependency>
And Gradle users, to their build file:
compile 'io.vertx:vertx-hawkular-metrics:3.5.0'
Vert.x does not enable SPI implementations by default. You must enable metric collection in the Vert.x options:
var Vertx = require("vertx-js/vertx");
var vertx = Vertx.vertx({
"metricsOptions" : {
"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 = require("vertx-js/vertx");
var vertx = Vertx.vertx({
"metricsOptions" : {
"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 = require("vertx-js/vertx");
var vertx = Vertx.vertx({
"metricsOptions" : {
"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 = require("vertx-js/vertx");
var vertx = Vertx.vertx({
"metricsOptions" : {
"enabled" : true,
"tenant" : "hawkular",
"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 = require("vertx-js/vertx");
var vertx = Vertx.vertx({
"metricsOptions" : {
"enabled" : true,
"tenant" : "my-namespace",
"httpHeaders" : {
"Authorization" : "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 = require("vertx-js/vertx");
var vertx = Vertx.vertx({
"metricsOptions" : {
"enabled" : true,
"host" : "hawkular.example.com",
"port" : 443,
"httpOptions" : {
"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 = require("vertx-js/vertx");
var vertx = Vertx.vertx({
"metricsOptions" : {
"enabled" : true,
"tags" : {
"dc" : "mars01",
"rack" : "web-paca",
"host" : "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 = require("vertx-js/vertx");
var vertx = Vertx.vertx({
"metricsOptions" : {
"enabled" : true,
"metricTagsMatches" : [{
"value" : "myapp.foo.my-metric",
"tags" : {
"myapp" : "foo"
}
}, {
"type" : "REGEX",
"value" : ".*\\.foo\\.*",
"tags" : {
"myapp" : "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 = require("vertx-js/vertx");
var vertx = Vertx.vertx({
"metricsOptions" : {
"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 = require("vertx-js/vertx");
var vertx = Vertx.vertx({
"metricsOptions" : {
"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 = {
"id" : "myapp.files.opened",
"value" : 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 = {
"id" : "myapp.files.opened",
"type" : "counter",
"timestamp" : 189898098098908,
"value" : 7
};
vertx.eventBus().publish("hawkular.metrics", counterMetric);
var availabilityMetric = {
"id" : "myapp.mysubsystem.status",
"type" : "availability",
"value" : "up"
};
vertx.eventBus().publish("hawkular.metrics", availabilityMetric);
|
Note
|
Hawkular understands all timestamps as milliseconds since January 1, 1970, 00:00:00 UTC. |