Time Series Metrics Engine based on Cassandra
Java Groovy XSLT Shell Scala HTML Other
Pull request Compare This branch is 503 commits behind hawkular:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
alerting
api
bus
clients
containers
core
data-generator
dist
integration-tests
job-scheduler
samples/rhmap
.gitignore
.travis.diagnose.sh
.travis.install.cassandra.sh
.travis.maven.settings.xml
.travis.swagger.sh
.travis.yml
CONTRIBUTING.adoc
LICENSE
README.adoc
pom.xml

README.adoc

Hawkular Metrics, a storage engine for metric data

Build Status
Coverity Scan Build Status (coverity_scan branch)

About

Hawkular Metrics is the metric data store for the Hawkular project. It can also be used independently.

It relies on Apache Cassandra as a backend and is comprised of:

  • a core library

  • a REST/HTTP interface

Important
Cassandra 3.7 or later is required. It is recommended to use the latest 3.7.x release if possible.

The core library

A Java library, built with RxJava on top of the Cassandra Java driver.

This is for advanced users only, if you want to embed the core functionnality in another product.

REST/HTTP interface

Most users will work with the web application. It exposes a REST/HTTP interface based on the core library. It is implemented with the JAX-RS 2 asynchronous API and runs on a Wildfly 10 server. The data format is JSON.

Goals

Simple, easy to use REST interface

The REST API should be easy to use. Users should be able to send data with the simplest tools: shell scripts and curl.

Getting started with a release build

Download a Wildfly 10 archive and expand it somewhere on your disk.

Check out the Metrics releases page and download the latest version of the web application archive: hawkular-metrics-api-jaxrs-X.Y.Z.war

Copy this file to the standalone/deployments directory of the Wildfly server.

Start the server with bin/standalone.sh.

By default, Metrics will try to connect to a Cassandra on localhost. If you want to start a Cassandra server embedded into Wildfly for testing, add the hawkular-metrics-embedded-cassandra-ear-X.Y.Z.ear archive to the standalone/deployments directory.

Build Instructions

Important
A running Cassandra cluster, which can be a single node, is required for unit and integration tests.
git clone git@github.com:hawkular/hawkular-metrics.git
cd hawkular-metrics
mvn install
Tip
If you only want to build the sources without a running C* cluster, you can run mvn install -DskipTests.

Setting up Cassandra for development or testing

For development or testing, the easiest way to setup Cassandra is to use the Cassandra Cluster Manager, CCM.

ccm create -v 3.7 hawkular
ccm populate -n 1
ccm start

These steps build and start a single node cluster of Cassandra. Note that while it is recommended to use ccm, it is not necessary. You just need to make sure you have a running 3.7.x cluster.

Client tools

If you want to send or fetch metrics from your own application, there are client libraries available to assist:

Working with monitoring tools

You can send data collected with your usual monitoring tools to Hawkular Metrics:

  • collectd

  • ganglia

  • jmxtrans

  • statsd

In order to do so, you must start our network protocol adapter, ptrans.

Contributing & Community

If you are a user of Hawkular Metrics please ask your question in the Hawkular user forum. To contribute or participate in design discussion, please use the Hawkular developer mailing list.

We love contributions and pull-requests :-)

To meet the guys, join us on Freenode IRC in channel #hawkular. If you can not use the irc protocol, you can also use a web to irc gateway like Web chat on Freenode.

Hawkular-Metrics is @hawkular_org on Twitter.