Carbon is one of the components of Graphite, and is responsible for receiving metrics over the network and writing them down to disk using a storage backend.

Daniel Lawrence 7d90b3cf3c extended the metricReceiver error to point user at the problem 6 years ago
bin 28fa6a1ae6 Refactor schema validation to be more informative 7 years ago
conf 58bf6d894c add description of aggregated-consistent-hashing 6 years ago
debian 7cef0beeba Adding debian postinstall script for carbon 6 years ago
distro f8c16f969a Test if chkconfig exists -- this allows RPMs to be converted with alien 6 years ago
examples af36d60bd0 - Copy over example-client.py, link to it 7 years ago
lib 7d90b3cf3c extended the metricReceiver error to point user at the problem 6 years ago
.gitignore 3502889def Add basic .gitignore 7 years ago
.travis.yml aada3b90be Add requirements.txt and travisci config, fix broken tests 7 years ago
LICENSE 9aeb881071 added carbon LICENSE and updated MANIFEST.in files 9 years ago
MANIFEST.in db3b0bec10 Move stuff to distro/ 6 years ago
README.md 9616683cc1 - Fix copy and paste error 7 years ago
requirements.txt aada3b90be Add requirements.txt and travisci config, fix broken tests 7 years ago
setup.cfg db3b0bec10 Move stuff to distro/ 6 years ago
setup.py bc7918787a Merge setup.py changes from master 6 years ago
stdeb.cfg 55edb6e7fe Add stdeb packaging for debian packages 6 years ago

README.md

Carbon

Build Status

Carbon is one of the components of Graphite, and is responsible for receiving metrics over the network and writing them down to disk using a storage backend. Currently Whisper is our stable, supported backend and Ceres is the work-in-progress future replacement for Whisper.

Overview

Client applications can connect to the running carbon-cache.py daemon on port 2003 (default) and send it lines of text of the following format:

my.metric.name value unix_timestamp

For example:

performance.servers.www01.cpuUsage 42.5 1208815315
  • The metric name is like a filesystem path that uses a dot as a separator instead of a forward-slash.

  • The value is some scalar integer or floating point value

  • The unix_timestamp is unix epoch time, as an integer.

Each line like this corresponds to one data point for one metric.

Alternatively, they can send pickle-formatted messages to port 2004 (default) which is considered faster than the line-based format.

Once you've got some clients sending data to carbon-cache, you can view graphs of that data through the frontend Graphite Web application.

Running carbon-cache.py

First you must tell carbon-cache what user it should run as. This must be a user with write privileges to $GRAPHITE_ROOT/storage/whisper. Specify the user account in $GRAPHITE_ROOT/conf/carbon.conf. This user must also have write privileges to $GRAPHITE_ROOT/storage/log/carbon-cache

Alternatively, you can run carbon-cache/carbon-relay/carbon-aggregator as Twistd plugins, for example:

Usage: twistd [options] carbon-cache [options]
Options:
      --debug       Run in debug mode.
  -c, --config=     Use the given config file.
      --instance=   Manage a specific carbon instance. [default: a]
      --logdir=     Write logs to the given directory.
      --whitelist=  List of metric patterns to allow.
      --blacklist=  List of metric patterns to disallow.
      --version     Display Twisted version and exit.
      --help        Display this help and exit.

Common options to twistd(1), like --pidfile, --logfile, --uid, --gid, --syslog and --prefix are fully supported and have precedence over carbon-*'s own options. Please refer to twistd --help for the full list of supported twistd options.

Writing a client

First you obviously need to decide what data it is you want to graph with graphite. The script examples/example-client.py demonstrates a simple client that sends loadavg data for your local machine to carbon on a minutely basis.

The default storage schema stores data in one-minute intervals for 2 hours. This is probably not what you want so you should create a custom storage schema according to the docs on the Graphite wiki.