Guide based on :
-
http://digitalronin.github.io/2014/04/29/installing-graphite-on-ubuntu-1404/
-
sudo apt-get install graphite-web graphite-carbon apache2 libapache2-mod-wsgi
During the installation, you will be asked whether you want Carbon to remove the database files if you ever decide to purge the installation. Choose "No" here so that you will not destroy your stats. If you need to start fresh, you can always manually remove the files (kept in var/lib/graphite/whisper).
Once you’ve got the packages installed, you need to tell apache to serve the Graphite web interface. You can do that by running these commands (as root);
sudo rm /etc/apache2/sites-enabled/000-default.conf
sudo ln -s /usr/share/graphite-web/apache2-graphite.conf /etc/apache2/sites-enabled/
Now setup the user database for django, like this;
sudo python /usr/lib/python2.7/dist-packages/graphite/manage.py syncdb
This will prompt you to setup an admin user and password. For now, let’s use ‘root’ and ‘foobar’. When that command has finished, you need to edit the file /etc/graphite/local_settings.py
sudo vim /etc/graphite/local_settings.py
You’ll see a line like this, near the top;
#SECRET_KEY = 'UNSAFE_DEFAULT'
Uncomment that line and replace UNSAFE_DEFAULT with some long random string.
SECRET_KEY = 'somelongrandomstring'
Next, we should specify the timezone. This will affect the time displayed on our graphs, so it is important to set. Set it to your time zone as specified by the "TZ" column in this list: http://en.wikipedia.org/wiki/List_of_tz_database_time_zones.
TIME_ZONE = 'Europe/Berlin'
Near the end of the file, you need to configure the user and password you created earlier;
DATABASES = {
'default': {
'NAME': '/var/lib/graphite/graphite.db',
'ENGINE': 'django.db.backends.sqlite3',
'USER': 'root',
'PASSWORD': 'foobar',
'HOST': '',
'PORT': ''
}
}
Note that this is using the default sqlite3 database backend. This is not recommended for production servers, so you will want to change that (and probably a lot of other things) when you’re ready to move your graphite server into production.
You may also need to change a couple of permissions;
sudo chmod 666 /var/lib/graphite/graphite.db
sudo chmod 755 /usr/share/graphite-web/graphite.wsgi
Now restart Apache
sudo /etc/init.d/apache2 restart
and you should be good to go. If you visit the IP address of your graphite server from a web browser, you should see the Graphite web interface.
If you have problems, you should be able to see what’s going on by looking in these log files;
tail -f /var/log/apache2/graphite-web_access.log
tail -f /var/log/apache2/graphite-web_error.log
Now that we have a database, we can start to configure Carbon, the Graphite storage backend.
First, let's enable the carbon service to start at boot. We can do this by opening the service configuration file:
sudo vim /etc/default/graphite-carbon
This only has one parameter, which dictates whether the service will start on boot. Change the value to "true":
CARBON_CACHE_ENABLED=true
Save and close the file.
Next, open the Carbon configuration file:
sudo vim /etc/carbon/carbon.conf
Most of this file is already configured correctly for our purposes. However, we will make a small change.
Turn on log rotation by adjusting setting this directive to true:
ENABLE_LOGROTATION = True
Save and close the file.
Now, open the storage schema file. This tells Carbon how long to store values and how detailed these values should be:
sudo vim /etc/carbon/storage-schemas.conf
Inside, you will find entries that look like this:
[carbon]
pattern = ^carbon\.
retentions = 60:90d
[default_1min_for_1day]
pattern = .*
retentions = 60s:1d
The file currently has two sections defined. The first one is for deciding what to do with data coming from Carbon itself. Carbon is actually configured to store some metrics of its own performance. The bottom definition is a catch-all that is designed to apply to any data that hasn't been matched by another section. It defines a default policy.
The words in the brackets are the section headers that are used to define a new definition. Under each section, there is a pattern definition and a retentions policy.
The pattern definition is a regular expression that is used to match any information sent to Carbon. Information sent to Carbon includes a metric name, which is what this checks. In the first example, the pattern checks whether the metric in question starts with the string "carbon.".
The retention policy is defined by sets of numbers. Each set consists of a metric interval (how often a metric is recorded), followed by a colon and then the length of time to store those values. You can define multiple sets of numbers separated by commas.
To demonstrate, we will define a new schema that will match a test value that we'll use later on.
Before the default section, add another section for our test values. Make it look like this:
[test]
pattern = ^test\.
retentions = 10s:10m,1m:1h,10m:1d
This will match any metrics beginning with "test.". It will store the data it collects three times, in varying detail. The first archive definition (10s:10m) will create a data point every ten seconds. It will store the values for only ten minutes.
The second archive (1m:1h) will create a data point every minute. It will gather all of the data from the past minute (six points, since the previous archive creates a point every ten seconds) and aggregate it to create the point. By default, it does this by averaging the points, but we can adjust this later. It stores the data at this level of detail for one hour.
The last archive that will be created (10m:1d) will make a data point every 10 minutes, aggregating the data in the same way as the second archive. It will store the data for one day.
When we request information from Graphite, it will return information from the most detailed archive that measures the time frame we're asking for. So if we ask for metrics from the past five minutes, information from the first archive will be returned. If we ask for a graph of the past 50 minutes, the data will be taken from the second archive.
Save and close the file when you are finished.
The way that Carbon decides to aggregate data when crunching more detailed information into a generalized number is very important to understand if you want accurate metrics. This applies every time that Graphite makes a less detailed version of a metric, like in the second and third archives in the test schema we created above.
As we mentioned above, the default behavior is to take the average when aggregating. This means that, other than the most detailed archive, Carbon will average the data points it received to create the number.
This is not always desirable though. For instance, if we want the total number of times that an event occurred over various time periods, we would want to add up the data points to create our generalized data point instead of averaging them.
We can define the way we want aggregation to occur in a file called storage-aggregation.conf. Copy the file from the Carbon examples directory into our Carbon configuration directory:
sudo cp /usr/share/doc/graphite-carbon/examples/storage-aggregation.conf.example /etc/carbon/storage-aggregation.conf
Open the file in your text editor:
sudo vim /etc/carbon/storage-aggregation.conf
This looks a bit similar to the last file. You will find entries that look like this:
[min]
pattern = \.min$
xFilesFactor = 0.1
aggregationMethod = min
The section name and pattern are exactly the same as the storage-schemas file. It is just an arbitrary name and a pattern to match the metrics you are defining.
The XFilesFactor is an interesting parameter in that it allows you to specify the minimum percentage of values that Carbon should have to do the aggregation. By default, all values are set to 0.5, meaning that 50% of the more detailed data points must be available if an aggregated point is to be created.
This can be used to ensure that you're not creating data points that might misrepresent the actual situation. For instance, if 70% of your data is being dropped because of network problems, you might not want to create a point that only truthfully represents 30% of the data.
The aggregation method is defined next. Possible values are average, sum, last, max and min. They are fairly self explanatory, but very important. Choosing the wrong value will cause your data to be recorded in an incorrect way. The correct selection depends entirely on what the metric is that you're actually tracking.
Note: It is important to realize that if you send Graphite data points more frequently than the shortest archive interval length, some of your data will be lost!
This is because Graphite only applies aggregation when going from detailed archives to generalized archives. When creating the detailed data point, it only writes the most recent data sent to it when the interval has passed. We will discuss StatsD in another guide, which can help alleviate this problem by caching and aggregating data that comes in at a more frequent interval.
Save and close the file.
When you are finished, you can start Carbon by typing:
sudo service carbon-cache start