Hawkular Services Getting Started Guide

Getting started with Hawkular

Install Hawkular

Please refer to the installation guide to install Hawkular Server. To execute the commands below, make sure to create a user myUsername with the password myPassword.

Step 1: Add metrics

In this quickstart guide, we’ll start by injecting metrics in the server. For this part we don’t need additional metadata nor tags on our metrics, we really want to start as quickly as possible, advanced features will be explained in other documents.

Let’s say we want to insert Weather temperature from a sensor so that we can keep an history and then visualize or alert on those values.

Hawkular Services provides different libraries for different languages, but here we will just use the REST API with CURL.

Copy the following content in a file named metrics_day_1.json, it contains weather data collected every 30 min for the whole day of July 15th 2016.

metrics_day_1.json
[
  {"timestamp": 1468533600000, "value": 10},
  {"timestamp": 1468535400000, "value": 10},
  {"timestamp": 1468537200000, "value": 9.7},
  {"timestamp": 1468539000000, "value": 9.6},
  {"timestamp": 1468540800000, "value": 9.6},
  {"timestamp": 1468542600000, "value": 9.6},
  {"timestamp": 1468544400000, "value": 9.5},
  {"timestamp": 1468546200000, "value": 9.5},
  {"timestamp": 1468548000000, "value": 9.5},
  {"timestamp": 1468549800000, "value": 9.5},
  {"timestamp": 1468551600000, "value": 9.5},
  {"timestamp": 1468553400000, "value": 9.5},
  {"timestamp": 1468555200000, "value": 9.6},
  {"timestamp": 1468557000000, "value": 9.6},
  {"timestamp": 1468558800000, "value": 9.7},
  {"timestamp": 1468560600000, "value": 9.7},
  {"timestamp": 1468562400000, "value": 9.8},
  {"timestamp": 1468564200000, "value": 10},
  {"timestamp": 1468566000000, "value": 10.2},
  {"timestamp": 1468567800000, "value": 10.3},
  {"timestamp": 1468569600000, "value": 10},
  {"timestamp": 1468571400000, "value": 9.9},
  {"timestamp": 1468573200000, "value": 10.1},
  {"timestamp": 1468575000000, "value": 9.7},
  {"timestamp": 1468576800000, "value": 9.2},
  {"timestamp": 1468578600000, "value": 9.2},
  {"timestamp": 1468580400000, "value": 9.9},
  {"timestamp": 1468582200000, "value": 11},
  {"timestamp": 1468584000000, "value": 12.4},
  {"timestamp": 1468585800000, "value": 13.3},
  {"timestamp": 1468587600000, "value": 14.3},
  {"timestamp": 1468589400000, "value": 13.6},
  {"timestamp": 1468591200000, "value": 11},
  {"timestamp": 1468593000000, "value": 10.2},
  {"timestamp": 1468594800000, "value": 10.1},
  {"timestamp": 1468596600000, "value": 10.3},
  {"timestamp": 1468598400000, "value": 10.9},
  {"timestamp": 1468600200000, "value": 11.4},
  {"timestamp": 1468602000000, "value": 11.7},
  {"timestamp": 1468603800000, "value": 11.5},
  {"timestamp": 1468605600000, "value": 11.1},
  {"timestamp": 1468607400000, "value": 10.6},
  {"timestamp": 1468609200000, "value": 10.1},
  {"timestamp": 1468611000000, "value": 9.6},
  {"timestamp": 1468612800000, "value": 9.2},
  {"timestamp": 1468614600000, "value": 9.1},
  {"timestamp": 1468616400000, "value": 9.1},
  {"timestamp": 1468618200000, "value": 9.1}
]

To insert metrics, we just need a running Hawkular Server and make sure we created a user according to the instructions. You can replace the values of the Hawkular-Tenant and temperature in the URL with the values of your choice, in this simple scenario, we don’t need to make additional calls to create those.

curl -u myUsername:myPassword -X POST http://localhost:8080/hawkular/metrics/gauges/temperature/raw -d @metrics_day_1.json -H "Content-Type: application/json" -H "Hawkular-Tenant: myTenant"

Now your data is stored in Hawkular Server, in it’s distributed Cassandra server. It’s ready to be used !

Step 2: Read the metrics

With Grafana

At the end of Step 1, you need to trust Hawkular that the data was indeed stored. The most elegant way to see the data is by setting up Grafana and its Hawkular plugin to actually build a dashboard and look at the temperature metric over that day (July 15th 2016) for myTenant. Here would be the result:

Grafana
Figure 1. Visualization of the metrics in Grafana

With the REST API

The metrics API provides ways to retrieve raw or downsampled values, here is a command to get back the raw value as we inserted earlier, for a part of the day. The URL is the same, the command is a GET instead of a POST and we added extra parameters to define from when to when we want the values, and that we want the data ordered by time.

Curl command
curl -u myUsername:myPassword \
  -X GET "http://localhost:8080/hawkular/metrics/gauges/temperature/raw?start=1468578600000&end=1468594800001&order=ASC" \
  -H "Content-Type: application/json" -H "Hawkular-Tenant: myTenant"

This would be the result of that command:

Command result
[
  {
    "timestamp": 1468578600000,
    "value": 9.2
  },
  {
    "timestamp": 1468580400000,
    "value": 9.9
  },
  {
    "timestamp": 1468582200000,
    "value": 11
  },
  {
    "timestamp": 1468584000000,
    "value": 12.4
  },
  {
    "timestamp": 1468585800000,
    "value": 13.3
  },
  {
    "timestamp": 1468587600000,
    "value": 14.3
  },
  {
    "timestamp": 1468589400000,
    "value": 13.6
  },
  {
    "timestamp": 1468591200000,
    "value": 11
  },
  {
    "timestamp": 1468593000000,
    "value": 10.2
  },
  {
    "timestamp": 1468594800000,
    "value": 10.1
  }
]

It is likely that the data will need to be downsampled, if there are too many data points in a short period of time. For instance to display two years of weather in a graph, the frequency every 30min is likely too much. The timeseries database allow to get "buckets" of data, which could be determined by the number of datapoints (size of the bucket) or the duration of a bucket. In this example, let’s say we want to know the minimum, maximum and average values for buckets that would last 2 hours. Since we have 24h of data, we should end up with 12 buckets of 4 data points (since we have 4 data points in 2h).

Percentiles
It is also possible to add percentiles values to the results, see the Metrics User Guide.
Curl command
curl -u myUsername:myPassword -X GET "http://localhost:8080/hawkular/metrics/gauges/temperature/stats?bucketDuration=2h&start=1468533600000&end=1468618200001" -H "Content-Type: application/json" -H "Hawkular-Tenant: myTenant"
Command result
[
  {
    "start": 1468533600000,
    "end": 1468540800000,
    "min": 9.6,
    "avg": 9.825,
    "median": 9.7,
    "max": 10,
    "sum": 39.3,
    "samples": 4,
    "empty": false
  },
  {
    "start": 1468540800000,
    "end": 1468548000000,
    "min": 9.5,
    "avg": 9.55,
    "median": 9.5,
    "max": 9.6,
    "sum": 38.2,
    "samples": 4,
    "empty": false
  },
  {
    "start": 1468548000000,
    "end": 1468555200000,
    "min": 9.5,
    "avg": 9.5,
    "median": 9.5,
    "max": 9.5,
    "sum": 38,
    "samples": 4,
    "empty": false
  },
  {
    "start": 1468555200000,
    "end": 1468562400000,
    "min": 9.6,
    "avg": 9.649999999999999,
    "median": 9.6,
    "max": 9.7,
    "sum": 38.6,
    "samples": 4,
    "empty": false
  },
  {
    "start": 1468562400000,
    "end": 1468569600000,
    "min": 9.8,
    "avg": 10.075,
    "median": 10,
    "max": 10.3,
    "sum": 40.3,
    "samples": 4,
    "empty": false
  },
  {
    "start": 1468569600000,
    "end": 1468576800000,
    "min": 9.7,
    "avg": 9.924999999999999,
    "median": 9.9,
    "max": 10.1,
    "sum": 39.699999999999996,
    "samples": 4,
    "empty": false
  },
  {
    "start": 1468576800000,
    "end": 1468584000000,
    "min": 9.2,
    "avg": 9.825,
    "median": 9.2,
    "max": 11,
    "sum": 39.3,
    "samples": 4,
    "empty": false
  },
  {
    "start": 1468584000000,
    "end": 1468591200000,
    "min": 12.4,
    "avg": 13.399999999999999,
    "median": 13.3,
    "max": 14.3,
    "sum": 53.6,
    "samples": 4,
    "empty": false
  },
  {
    "start": 1468591200000,
    "end": 1468598400000,
    "min": 10.1,
    "avg": 10.399999999999999,
    "median": 10.2,
    "max": 11,
    "sum": 41.599999999999994,
    "samples": 4,
    "empty": false
  },
  {
    "start": 1468598400000,
    "end": 1468605600000,
    "min": 10.9,
    "avg": 11.375,
    "median": 11.4,
    "max": 11.7,
    "sum": 45.5,
    "samples": 4,
    "empty": false
  },
  {
    "start": 1468605600000,
    "end": 1468612800000,
    "min": 9.6,
    "avg": 10.35,
    "median": 10.1,
    "max": 11.1,
    "sum": 41.4,
    "samples": 4,
    "empty": false
  },
  {
    "start": 1468612800000,
    "end": 1468620000000,
    "min": 9.1,
    "avg": 9.125,
    "median": 9.1,
    "max": 9.2,
    "sum": 36.5,
    "samples": 4,
    "empty": false
  }
]
Learn more
We only scratched the surface of what we can do when storing and retrieving metrics, in the Metrics User Guide you will see how to tag metrics, aggregate values from various metrics and other advanced features.

Step 3: Add alerting

We saw how to add metrics, visualize those and make some computation, now we’ll see how to be notified for particular conditions. An alert trigger consists of:

  • A set of conditions to trigger the alert/event

  • One or multiple actions to take when the conditions are met (send an email, call a webhook, start/stop new docker containers or VM for autoscaling…​)

  • Some additional metadata (such as the severity, a description or business context)

Here is the example we will use, we put everything in a single file while in practice the actions may be separated as they are reusable among various triggers. This basic example would send an email to 'admin@example.org' if the temperature gets below 0 degrees Celcius (Water freezing point)

trigger_definition.json
{
  "triggers": [
    {
      "trigger": {
        "id": "temperature-trigger",
        "name": "Trigger for the temperature sensor",
        "severity": "HIGH",
        "enabled": true,
        "actions": [
          {
            "actionPlugin": "email",
            "actionId": "notify-admin"
          }
        ]
      },
      "conditions": [
        {
          "triggerMode": "FIRING",
          "type": "threshold",
          "dataId": "hm_g_temperature",
          "operator": "LT",
          "threshold": 0
        }
      ]
    }
  ],
  "actions": [
    {
      "actionPlugin": "email",
      "actionId": "notify-admin",
      "properties": {
        "to": "admin@example.org"
      }
    }
  ]
}

To import that trigger definition, we’ll use the import command of the REST API:

curl -u myUsername:myPassword -X POST http://localhost:8080/hawkular/alerts/import/all -d @includes/alert-definition.json \
   -H "Content-Type: application/json" -H "Hawkular-Tenant: myTenant"

Step 4: Test the alert trigger

From now on, if we enter metrics that satisfy the condition, an email would be send (assuming an email server is available and configured). Let’s try to enter more metrics, similar to what we did earlier.

metrics_day_2.json
[
  {"timestamp": 1468620000000, "value": 8},
  {"timestamp": 1468621800000, "value": 6},
  {"timestamp": 1468623600000, "value": 3},
  {"timestamp": 1468625400000, "value": 0},
  {"timestamp": 1468627200000, "value": -2},
  {"timestamp": 1468629000000, "value": -3},
  {"timestamp": 1468630800000, "value": -1},
  {"timestamp": 1468632600000, "value": 2},
  {"timestamp": 1468634400000, "value": 4},
  {"timestamp": 1468636200000, "value": 5},
  {"timestamp": 1468638000000, "value": 8},
  {"timestamp": 1468639800000, "value": 12},
  {"timestamp": 1468641600000, "value": 13},
  {"timestamp": 1468643400000, "value": 12},
  {"timestamp": 1468645200000, "value": 13.4},
  {"timestamp": 1468647000000, "value": 14},
  {"timestamp": 1468648800000, "value": 14.3},
  {"timestamp": 1468650600000, "value": 14.6},
  {"timestamp": 1468652400000, "value": 17},
  {"timestamp": 1468654200000, "value": 17.3},
  {"timestamp": 1468656000000, "value": 17.5},
  {"timestamp": 1468657800000, "value": 17.9},
  {"timestamp": 1468659600000, "value": 18},
  {"timestamp": 1468661400000, "value": 18.7},
  {"timestamp": 1468663200000, "value": 19.2}
]

And execute the command to store the metrics (and will evaluate against our alert trigger conditions):

curl -u myUsername:myPassword -X POST http://localhost:8080/hawkular/metrics/gauges/temperature/raw -d @metrics_day_2.json \
   -H "Content-Type: application/json" -H "Hawkular-Tenant: myTenant"

In the logs of Hawkular Services, you should see 3 INFO messages showing that the conditions were met such as:

11:59:37,361 INFO  [org.hawkular.alerts.actions.api] (Thread-251 (ActiveMQ-client-global-threads-1118700939)) HAWKALERT240001: Plugin [email] has received an action message: [BusActionMessage[action=Action[eventId='temperature-trigger-1472551176767-dc41aaf3-bdd7-4a89-a950-44dc92f10c8b', ctime=1472551176769, event=Alert [alertId=temperature-trigger-1472551176767-dc41aaf3-bdd7-4a89-a950-44dc92f10c8b, status=OPEN, ackTime=0, ackBy=null, resolvedTime=0, resolvedBy=null, context={}], result='null']]]
11:59:37,385 INFO  [org.hawkular.alerts.actions.api] (Thread-242 (ActiveMQ-client-global-threads-1118700939)) HAWKALERT240001: Plugin [email] has received an action message: [BusActionMessage[action=Action[eventId='temperature-trigger-1472551176770-300fda0d-2c82-46e3-9f09-f4e9ed4ffa3a', ctime=1472551176771, event=Alert [alertId=temperature-trigger-1472551176770-300fda0d-2c82-46e3-9f09-f4e9ed4ffa3a, status=OPEN, ackTime=0, ackBy=null, resolvedTime=0, resolvedBy=null, context={}], result='null']]]
11:59:37,384 INFO  [org.hawkular.alerts.actions.api] (Thread-253 (ActiveMQ-client-global-threads-1118700939)) HAWKALERT240001: Plugin [email] has received an action message: [BusActionMessage[action=Action[eventId='temperature-trigger-1472551176759-90040813-1b7a-4bda-ac65-1c7f673d4daa', ctime=1472551176760, event=Alert [alertId=temperature-trigger-1472551176759-90040813-1b7a-4bda-ac65-1c7f673d4daa, status=OPEN, ackTime=0, ackBy=null, resolvedTime=0, resolvedBy=null, context={}], result='null']]]

More

Congratulations, you just scratched the surface of Hawkular Services!

We played with basic metrics and alerting capabilities, both have more advanced features and we didn’t tackle the inventory service in this getting started guide.

More details are available in the Hawkular Services user guide and the various REST APIs documentations: Alerting REST API, Metrics REST API and Inventory REST API

Note that multiple client libraries have been written already, and some agents that can collect or listen to metrics to feed the system. Have a look at the clients page to see what it supported as of today (We love contributions!)

redhatlogo-white

© 2016 | Hawkular is released under Apache License v2.0