Installation

Installing Graphite

Requirements

Graphite requires:

  • python2.4 or greater
  • pycairo (with PNG backend support)
  • mod_python
  • django
  • python-ldap (optional - needed for ldap-based webapp authentication)
  • python-memcached (optional - needed for webapp caching, big performance boost)
  • python-sqlite2 (optional - a django-supported database module is required)
  • bitmap and bitmap-fonts required on some systems, notably Red Hat

Get the packages from Launchpad.net

There are 3 packages called whisper, carbon, and graphite-web. They are available at https://launchpad.net/graphite/+download/

You can also use the latest source by checking it out with git:

# Master (unstable/alpha) branch
git clone https://github.com/graphite-project/graphite-web.git
git clone https://github.com/graphite-project/carbon.git
git clone https://github.com/graphite-project/whisper.git
# 0.9.x (stable) branch
git clone https://github.com/graphite-project/graphite-web.git
cd graphite-web
git checkout 0.9.x
cd ..
git clone https://github.com/graphite-project/carbon.git
cd carbon
git checkout 0.9.x
cd ..
git clone https://github.com/graphite-project/whisper.git
cd whisper
git checkout 0.9.x
cd ..

Install Whisper

pushd whisper
sudo python setup.py install
popd

Install Carbon

By default, everything will be installed in /opt/graphite

To install carbon:

pushd
python setup.py install 
popd

Configure Carbon

pushd /opt/graphite/conf
cp carbon.conf.example carbon.conf
cp storage-schemas.conf.example storage-schemas.conf

The default values in the examples are sane, but it is strongly recommended to consider how much data you would like to retain. By default, it will be saved for 1 day in 1 minute intervals. This is set in the whisper files individually, and changing the value here will not alter existing metrics. A conversion script shipped with Whisper (whisper-resize.py) can be used to change these later. Many people will want to store more than one day's worth of data. If you think that you may want to track trends week over week, month over month or year over year, you may want to store 13 months (1 year + 1 month) or perhaps even 2 - 3 years worth of data. If you want to learn more about data retentions, please click here.

Here is an example of the 13-month retention example (giving you a month of overlap when comparing metrics year-over-year):

Note: Priority is not used. **
Rules are applied in the order they appear in the file**

[everything_1min_13months]
priority = 100
pattern = .*
retentions = 1m:395d

Be sure to replace the entire [everything_1min_1day] section with this example.

Configure the Graphite webapp

This is the frontend / webapp that renders the images.

pushd graphite-web
python check-dependencies.py
popd

Use your distribution's package manager or any other means to install the required software.

Once the dependencies are met, install Graphite:

pushd graphite-web
python setup.py install
popd

Configure Apache

There is an example example-graphite-vhost.conf file in the examples directory of the graphite web source code. You can use this to configure apache. Different distributions have different ways of configuring Apache. Please refer to your distribution's documentation on the subject.

For example, Ubuntu uses /etc/apache2/sites-available and sites-enabled/ to handle this (A symlink from sites-enabled/ to sites-available/ would be used after placing the file in sites-available/).

Others use an Include directive in the httpd.conf file like this:

# This goes in httpd.conf
Include /usr/local/apache2/conf/vhosts.d/*.conf

The configuration files must then all be added to /usr/local/apache2/conf/vhosts.d/.

Still others may not help handle this at all and you must add the configuration to your http.conf file directly.

Graphite will be in the DocumentRoot of your webserver, and will not allow you to access plain-HTML in subdirectories without addition configuration. You may want to edit the example-graphite-vhosts.conf file to change port numbers or use additional "SetHandler None" directives to allow access to other directories.

Be sure to reload your Apache configuration.

sudo /etc/init.d/apache2 reload

or

sudo /etc/init.d/httpd reload

Initial Database Creation

You must tell Django to create the database tables used by the graphite webapp. This is very straight forward, especially if you are using the default sqlite setup.

NOTE: If you are using a custom database backend (other than sqlite) you must first create a $GRAPHITE_ROOT/webapp/graphite/local_settings.py file that overrides the database related settings from settings.py. Use $GRAPHITE_ROOT/webapp/graphite/local_settings.py.example as a template.

Assuming you are using the default setup, you should be able to create the database with the following commands:

cd /opt/graphite/webapp/graphite
sudo python manage.py syncdb

You will be prompted to create an admin user; most people will want to do this.

Now you must change ownership of the database file to the same user that owns the Apache processes.
If your distribution has apache run as user 'nobody':

sudo chown nobody:nobody /opt/graphite/storage/graphite.db

This varies widely among different distributions.

If you use a backend such as mysql or postgres, the DATABASE_USER you create in your local_settings.py must have permission to create tables under the database named by DATABASE_NAME.

Restart apache and you should see the graphite webapp on the main page. If you encounter problems, you can increase the verbosity of error by creating a local_settings file.

cd /opt/graphite/webapp/graphite
cp local_settings.py.example local_settings.py

Uncomment the following line in /opt/graphite/webapp/graphite/local_settings.py
# DEBUG = True

Also remember that the apache logs for the graphite webapp in the graphite-example-vhost.conf are in /opt/graphite/storage/logs/

Start Carbon (the data aggregator)

cd /opt/graphite/
./bin/carbon-cache.py start

Next Steps

Now you have finished installing graphite, the next thing to do is put some real data into it. This is accomplished by sending it some data as demonstrated in the included
./examples/example-client.py

Click here to continue to the next page:
Getting your data into Graphite.

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