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.3.0.CR2</version>
</dependency>
And Gradle users, to their build file:
compile 'io.vertx:vertx-hawkular-metrics:3.3.0.CR2'
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 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 |
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 that 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. |
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.