Build Status Coverage Status

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:

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.

Contributing to hawkular-client-ruby

Running the tests

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

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