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:
def 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:
def 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:
def 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:
def 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:
def 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:
def 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:
def 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:
def 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:
def 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:
def 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:
def 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:
def counterMetric = [
id:"myapp.files.opened",
type:"counter",
timestamp:189898098098908L,
value:7
]
vertx.eventBus().publish("hawkular.metrics", counterMetric)
def 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. |