Quickstart Guide

Introduction

This guide will detail the various steps to get graphite up and running quickly from the latest source code. This will help you get a quick idea of what graphite is about, and you will familiarize yourself with the various components of the application.

We assume that know your way around a Linux system, and know the software package management for your particular distribution, etc.

Get the source

Get the bazaar SCM packages installed, and do:

timo@plageis:/opt$ bzr branch lp:graphite

From now on we'll assume you are using /opt/graphite as the root of the graphite tree like me.

External dependencies

Start by running check-dependencies.py to verify and install all the needed software:

timo@plageis:/opt/graphite$ ./check-dependencies.py

Refer to the INSTALL file for the latest dependency information.

Initialize the database

timo@plageis:/opt/graphite$ PYTHONPATH=`pwd`/webapp:`pwd`/whisper python ./webapp/graphite/manage.py syncdb
Creating table account_profile
Creating table account_variable
...

Django will likely want you to create some kind of admin account, just go ahead and do that too.

Run the web interface under the django development server

Start by enabling debug mode in a local_settings.py file:

timo@plageis:/opt/graphite$ echo DEBUG = True > webapp/graphite/local_settings.py

Refer to webapp/graphitelocal_settings.py.example// for more info on this file.

Run the development server:

timo@plageis:/opt/graphite$ PYTHONPATH=`pwd`/whisper ./bin/run-graphite-devel-server.py --libs=`pwd`/webapp/ /opt/graphite/

Note that PYTHONPATH has the path to the whisper subsystem, which is the part of the application that deals with data storage and management.

By default the server will listen on port 8080, point your web browser to //http://127.0.0.1:8080///.

You should now see the graphite interface. If not the debug mode configuration should give you enough information to diagnose and fix things.

Start the data collection daemon

You need a carbon.conf configuration first:

timo@plageis:/opt/graphite$ cp carbon/conf/carbon.conf.example carbon/conf/carbon.conf
timo@plageis:/opt/graphite$ PYTHONPATH=`pwd`/whisper ./carbon/bin/carbon-cache.py --debug start

If you get an error about "unexpected keyword argument 'dict_type'", see https://bugs.launchpad.net/graphite/+bug/478681

carbon-cache.py will start a listener on port 2003 that will wait for data to be submitted. You can remove the —debug option later so it forks in the background.

Feed some data

Run example-client.py:

timo@plageis:/opt/graphite$ python ./examples/example-client.py 
sending message

--------------------------------------------------------------------------------
system.loadavg_1min 1.05 1257715746
system.loadavg_5min 1.20 1257715746
system.loadavg_15min 1.27 1257715746

The data will be stored under storage/whisper directory:

timo@plageis:/opt/graphite$ ls -1l storage/whisper/system/
total 384
-rw-r--r-- 1 timo timo     21 2009-11-08 15:29 loadavg_15min.context.pickle
-rw-r--r-- 1 timo timo 120988 2009-11-08 15:31 loadavg_15min.wsp
-rw-r--r-- 1 timo timo     21 2009-11-08 15:29 loadavg_1min.context.pickle
-rw-r--r-- 1 timo timo 120988 2009-11-08 15:31 loadavg_1min.wsp
-rw-r--r-- 1 timo timo     21 2009-11-08 15:29 loadavg_5min.context.pickle
-rw-r--r-- 1 timo timo 120988 2009-11-08 15:31 loadavg_5min.wsp

And will start appearing in the web interface.

NOTE: I am actually having a problem getting that example-client data to appear under the tree, which I'm currently investigating.

Troubleshooting

Try this to watch the various logs if something is not working right:

timo@plageis:/opt/graphite$ find . -name '*.log' | xargs tail -F

Where to go from there

You can use Apache and mod_python to host a production setup. Read the INSTALL file for more details. You will also be able to install the various modules system wide with the distutils scripts (whisper in particular).

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License