Need help with hawkular-metrics?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

hawkular
226 Stars 76 Forks Apache License 2.0 3.2K Commits 12 Opened issues

Description

Time Series Metrics Engine based on Cassandra

Services available

!
?

Need anything else?

Contributors list

= 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/#!/hawkularorg/[@hawkularorg] on Twitter.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.