Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/hawkular/hawkular-metrics

Time Series Metrics Engine based on Cassandra
https://github.com/hawkular/hawkular-metrics

alerting hawkular java metrics monitoring time-series

Last synced: 9 months ago
JSON representation

Time Series Metrics Engine based on Cassandra

Awesome Lists containing this project

README 

          
= Hawkular Metrics, a storage engine for metric data

:source-language: java



// just major.minor

:cassandra-version: 3.0.12



ifdef::env-github[]

[link=https://travis-ci.org/hawkular/hawkular-metrics]

image::https://travis-ci.org/hawkular/hawkular-metrics.svg?branch=master[Build Status,70,18]

[link=https://scan.coverity.com/projects/4581"]

image::https://scan.coverity.com/projects/4581/badge.svg[Coverity Scan Build Status (coverity_scan branch)]

endif::[]



== About



Hawkular Metrics is the metric data storage engine part of http://www.hawkular.org/[Hawkular] community.



It relies on https://cassandra.apache.org/[Apache Cassandra] as a backend and is comprised of:



- a core library

- a REST/HTTP interface



IMPORTANT: Cassandra {cassandra-version} or later is required.



=== The core library



A Java library, built with https://github.com/ReactiveX/RxJava[RxJava] on top of the Cassandra Java driver.



This is for advanced users only, for embedding the core functionality in another project.



=== REST/HTTP interface



Most users will work with the

https://github.com/hawkular/hawkular-metrics/tree/master/api/metrics-api-jaxrs[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 http://www.wildfly.org/[Wildfly 10] server. The data format is JSON.



== Goals



=== Simple, easy to use REST interface



The http://www.hawkular.org/docs/rest/rest-metrics.html[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

There are a couple of options for running Hawkular Metrics:



* WildFly distribution

* EAR distribution



IMPORTANT: Earlier versions of Hawkular Metrics could be run by deploying `hawkular-metrics-api-jaxrs-X.Y.Z.war`. This

is longer supported.



The WildFly distribution is a pre-configured WildFly 10 server that includes Hawkular Alerts in addition to Hawkular

Metrics. Check out the https://github.com/hawkular/hawkular-metrics/releases[Metrics releases] page and download the latest

version of `hawkular-metrics-wildfly-standalone-X.Y.Z.Final.tar.gz`.



The EAR distribution includes both Hawkular Metrics and Hawkular Alerts. Check out the

https://github.com/hawkular/hawkular-metrics/releases[Metrics releases] page and download the latest version of

`hawkular-metrics-standalone-dist-X.Y.Z.Final.ear`. Copy the EAR file to the `standalone/deployments` directory. You

will have to manually configure WildFly.



The following cache container declarations are needed in the infinispan

subsection:



[source,xml]

----



      

      

      

      

      

      

      



        



----



If you are running a cluster of WildFly servers in HA mode, then you will instead want to edit standalone-ha.xml,

adding the following cache containers:



[source,xml]

----



        

        

               

        

        

               

        

        

               

        

        

               

        

        

               

        

        

               

        

        

               

        



        

        

               

        



----



By default, Metrics will try to connect to a Cassandra on localhost. If you want to start a Cassandra server

embedded in 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.



[source,bash]

----

git clone git@github.com:hawkular/hawkular-metrics.git

cd hawkular-metrics

./mvnw install

----



TIP: If you only want to build the sources without a running C* cluster, you can run `./mvnw install -DskipTests`.



== Setting up Cassandra for development or testing



For development or testing, the easiest way to setup Cassandra is to use the

https://github.com/pcmanus/ccm[Cassandra Cluster Manager, CCM].



[source,bash,subs="attributes"]

----

ccm create -v {cassandra-version} -n 1 -s hawkular

----



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 {cassandra-version} cluster.



== Client tools



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



- https://github.com/hawkular/hawkular-client-python[Python]

- https://github.com/hawkular/hawkular-client-go[Go]

- https://github.com/hawkular/hawkular-client-ruby[Ruby]

- https://github.com/hawkular/hawkular-client-java[Java]



== 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,

https://github.com/hawkular/hawkular-metrics/tree/master/clients/ptranslator[ptrans].



== Contributing & Community



If you are a user of Hawkular Metrics please ask your question in the

https://developer.jboss.org/discussion/create.jspa?containerType=14&containerID=2351[Hawkular user forum].

To contribute or participate in design discussion, please use the

https://lists.jboss.org/mailman/listinfo/hawkular-dev[Hawkular developer mailing list].



We love contributions and pull-requests :-)



To file an issue, please use the http://issues.jboss.org/browse/HWKMETRICS[Hawkular-Metrics JIRA].



To chat, join us on irc://irc.freenode.net/#hawkular[Freenode IRC] in channel #hawkular.

If you can not use the irc protocol, you can also use a web to irc gateway like

http://webchat.freenode.net/?channels=hawkular[Web chat on Freenode].



Hawkular-Metrics is http://twitter.com/#!/hawkular_org/[@hawkular_org] on Twitter.