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
,EventBus
and handlers -
User defined metrics via an
EventBus
bridge.
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.2.0</version>
</dependency>
And Gradle users, to their build file:
compile 'io.vertx:vertx-hawkular-metrics:3.2.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
}
});
Hawkular tenant selection
Hawkular 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"
}
});
HTTPS and over 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 that all the usual HttpClientOptions
properties can be used for SSL setup or client
tuning.
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 |
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 vertx;
var message = {
"id" : "myapp.files.opened",
"value" : 7
};
vertx.eventBus().publish("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 if you prefer explicit configuration, set the type
and
timestamp
attributes:
var vertx;
var message = {
"id" : "myapp.files.opened",
"type" : "counter",
"timestamp" : 189898098098908,
"value" : 7
};
vertx.eventBus().publish("metrics", message);
Note that Hawkular understands all timestamps as milliseconds since January 1, 1970, 00:00:00 UTC.