hawkular-client-ruby

A Ruby Hawkular Client.

Documentation

Changelog

See CHANGELOG for a list of changes and API-Breaking-Changes for a list of api-breaking changes.

Overview

Ruby Hawkular Client provides a Ruby API to communicate with the following Hawkular subprojects:

Hawkular Alerts
Hawkular Inventory
Hawkular Metrics
Invoking operations on Hawkular Wildfly Agent.

Usage

You must initialize the Hawkular Client with the server url, your username, password and tenant.

require 'hawkular/hawkular_client'
client = Hawkular::Client.new(
  entrypoint: 'http://localhost:8080',
  credentials: { username: 'jdoe', password: 'password' },
  options: { tenant: 'hawkular' }
)

Each subproject API is packed in its own class, which you can access through the client object.

client.alerts # Alerts API
client.inventory # Inventory API
client.metrics # Metrics API
client.operations # Operations API

Metrics API is also subdivided to: Mixed, Availability, Counters, Gauges and Tenants.

client.metrics # Mixed API
client.metrics.avail # Availability
client.metrics.counters # Counters
client.metrics.gauges # Gauges
client.metrics.tenants # Tenants

The Mixed API is capable of handling multiple types of metrics, like the push_data method, which pushes data for multiple metrics of all supported data.

You can also access each subproject's API individually, if you would like to use only the metrics API you could do

require 'hawkular/metrics/metrics_client'
metrics_client = Hawkular::Metrics::Client.new(
  entrypoint: 'http://localhost:8080/hawkular/metrics',
  credentials: { username: 'jdoe', password: 'password' },
  options: { tenant: 'hawkular' }
)

HTTP and HTTPS options

Will all client classes, the :options hash can contain extra parameters passed through to RestClient gem. It can include a :headers sub-hash to add custom headers:

require 'hawkular/hawkular_client'
client = Hawkular::Client.new(
  entrypoint: 'http://localhost:8080',
  credentials: { username: 'jdoe', password: 'password' },
  options: { tenant: 'hawkular', proxy: 'proxy.example.com', ssl_ca_file: 'ca.pem',
             headers: {'Max-Forwards': 5} }
)

Examples

Suppose you will monitor the availability of two networks to later determine which one is the best. Every certain time, you would get the availability of each network and push them to Hawkular Metrics.

# ... Initialize client ...
is_network01_available = true
is_network02_available = false
client.metrics.push_data(availabilities: [
  { id: 'network-01', data: [{ value: is_network01_available ?  'up' : 'down' }] },
  { id: 'network-02', data: [{ value: is_network02_available ?  'up' : 'down' }] }
])

At some other point you might want to access that data to analyze it

# ... Initialize client ...
# Fetches the 5 last availabilities reported in the last 8 hours.
network01_avail = client.metrics.avail.get_data('network-01', limit: 5, order: 'DESC')
network02_avail = client.metrics.avail.get_data('network-02', limit: 5, order: 'DESC')
# ... Do something with the availabilities ...

Each network01_avail will be an array like:

[
  { "timestamp" => 1467312571473, "value" => "up" },
  { "timestamp" => 1467312492650, "value" => "up" },
  # ...
]

You can get more info on the other parameters by checking the metrics API get_data

More info

Check each resource API for a detailed description of what methods are available.

Alerts
Inventory
Metrics:
- Mixed
- Availability
- Counters
- Gauges
- Tenants
Operations

Contributing to hawkular-client-ruby

Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
Fork the project
Start a feature/bugfix branch
Commit and push until you are happy with your contribution
Make sure to add tests for it. This is important so it won't break in a future version unintentionally.
Run your code through RuboCop (which is default when running rake) and fix complaints.
When you open a pull request, watch out for failures on Travis.
Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so we can cherry-pick around it.

Running the tests

Integration tests are recorded and played against cassettes recorded with VCR (www.relishapp.com/vcr/vcr/docs)

Edit the endpoint properties in the file spec/endpoint.yml (user, password and host name) if needed
From command line run
```
rake spec
```
To run the tests against a live server, set VCR_OFF to 1 as in
```
VCR_OFF=1 rake spec
```
To update the VCR tapes that supports it (metrics and inventory), set VCR_UPDATE to 1 as in
```
VCR_UPDATE=1 rake spec
```
Currently, we support two posible metrics contexts: hawkular-metrics 0.8.0.Final and hawkular-services that contain metrics. If you want to run/re-record the tests only for services, you can skip the other context by SKIP_V8_METRICS=1, or similarly SKIP_SERVICES_METRICS=1. So for instance updating the VCR templates only for hawkular-services would require command:
```
VCR_UPDATE=1 SKIP_V8_METRICS=1 rspec ./spec/integration/metric_spec.rb
```

For more details consult the spec readme.

Logging

If you want to see API requests and responses, use the following environment variables:

RESTCLIENT_LOG=stdout HAWKULARCLIENT_LOG_RESPONSE=1 rake spec

Generate documentation

Client documentation can be generated using yardoc.org

yardoc