hawkular-metrics

hawkular-metrics copied to clipboard

= 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 [email protected]: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.