This project has retired. For details please refer to its Attic page.
Apache Chukwa -

Apache Chukwa Quick Start Guide


Apache Chukwa is a system for large-scale reliable log collection and processing with Hadoop. Apache Chukwa design overview discusses the overall architecture of Apache Chukwa. You should read that document before this one. The purpose of this document is to help you install and configure Apache Chukwa.


Apache Chukwa should work on any POSIX platform, but GNU/Linux is the only production platform that has been tested extensively. Apache Chukwa has also been used successfully on Mac OS X, which several members of the Apache Chukwa team use for development.

Software requirements are Java 1.6 or better, ZooKeeper 3.4.5, HBase 1.2.0 and Hadoop 2.7.2.

Apache Chukwa cluster management scripts rely on ssh; these scripts, however, are not required if you have some alternate mechanism for starting and stopping daemons.

Installing Apache Chukwa

A minimal Apache Chukwa deployment has five components:

  • A Apache Hadoop and Apache HBase cluster on which Apache Chukwa will process data (referred to as the Chukwa cluster).
  • One or more agent processes, that send monitoring data to Apache HBase. The nodes with active agent processes are referred to as the monitored source nodes.
  • Solr Cloud cluster which Apache Chukwa will store indexed log files.
  • Data analytics script, summarize Hadoop Cluster Health.
  • HICC, Apache Chukwa visualization tool.
Apache Chukwa 0.8.0 Architecture

First Steps

  • Obtain a copy of Apache Chukwa. You can find the latest release on the Apache Chukwa release page (or alternatively check the source code out from SCM).
  • Un-tar the release, via tar xzf.
  • Make sure a copy of Apache Chukwa is available on each node being monitored.
  • We refer to the directory containing Apache Chukwa as CHUKWA_HOME. It may be useful to set CHUKWA_HOME explicitly in your environment for ease of use.

Setting Up Apache Chukwa Cluster

Configure Hadoop and HBase

  1. Copy Apache Chukwa files to Hadoop and HBase directories:
    cp $CHUKWA_HOME/etc/chukwa/ $HADOOP_CONF_DIR/
    cp $CHUKWA_HOME/etc/chukwa/ $HADOOP_CONF_DIR/
    cp $CHUKWA_HOME/share/chukwa/chukwa-0.8.0-client.jar $HADOOP_HOME/share/hadoop/common/lib
    cp $CHUKWA_HOME/share/chukwa/lib/json-simple-1.1.jar $HADOOP_HOME/share/hadoop/common/lib
    cp $CHUKWA_HOME/etc/chukwa/ $HBASE_CONF_DIR/
    cp $CHUKWA_HOME/etc/chukwa/ $HBASE_CONF_DIR/
    cp $CHUKWA_HOME/share/chukwa/chukwa-0.8.0-client.jar $HBASE_HOME/lib
    cp $CHUKWA_HOME/share/chukwa/lib/json-simple-1.1.jar $HBASE_HOME/lib
  2. Restart your Hadoop Cluster. General Hadoop configuration is available at: Hadoop Configuration. N.B. You may see some additional logging messages at this stage which looks as if error(s) are present. These messages are showing up because the log4j socket appender writes to stderr for warn messages when it is unable to stream logs to a log4j socket server. If Apache Chukwa agent is started with socket adaptors prior to Hadoop and HBase, those messages will not show up. For the time being do not worry about these messages, they will disappear once Apache Chukwa agent is started with socket adaptors.
  3. Make sure HBase is started. General HBASE configuration is available at: HBase Configuration
  4. After Hadoop and HBase are started, run:
    bin/hbase shell < $CHUKWA_HOME/etc/chukwa/hbase.schema

    This procedure initializes the default Apache Chukwa HBase schema.

Configuring And Starting Apache Chukwa Agent

  1. Edit CHUKWA_HOME/etc/chukwa/ Make sure that JAVA_HOME, HADOOP_CONF_DIR, and HBASE_CONF_DIR are set correctly.
  2. Edit CHUKWA_HOME/etc/chukwa/chukwa-agent-conf.xml. Make sure that are set correctly.
  3. In CHUKWA_HOME, run:
    sbin/ start agent

Setup Solr to index Service log files

  1. Start Solr 5.5.0 with Apache Chukwa Solr configuration:
    bin/solr start -cloud -z localhost:2181
    ./bin/solr create_collection -c chukwa -n chukwa

Start HICC

The Hadoop Infrastructure Care Center (HICC) is Apache Chukwa web user interface.

  1. To start HICC, do the following:
    sbin/ start hicc

Data Visualization

  1. Once the webcontainer with HICC has been started, point your favorite browser to:
  2. The default user name and password is "admin" without quotes.
  3. Metrics data collected by Apache Chukwa Agent will be browsable through Graph Explorer widget.