Skip to main content

Utilities for querying graphite's database

Project description


graphite-query is a library created from graphite-web in order to make some of its functionality framework neutral, i.e. to require as little dependencies as possible.


You can install graphite-query by running:

pip install graphite-query

You can also download/clone the github repository, and, inside the directory where you downloaded graphite-query run:

python install


This package provides the functions query, eval_qs and get_all_leaf_nodes (all are part of the graphitequery.query subpackage).


query takes both positional and keyword arguments, which in turn are taken from graphite-web’s render API except for the graph/format arguments, which are, of course, inapplicable to graphite-query.

In short, its parameters (in positional order) are:

A basic query might look like this:

>>> from graphitequery.query import query
>>> print list(query("graphite-web.compatible.path.expression")[0])

The query function always (even if you supply only one target path) returns a list of instances of graphitequery.query.datalib.TimeSeries, which in turn is a list-like object whose sub-elements are the values stored by graphite (in a whisper database) at particular points in time.


This is a helper function: it takes a URL query string as a parameter. The query string must be compatible with the graphite-web’s render controller. eval_qs internally converts this string to a parameter dictionary that can be passed on to query and calls query.E.g.:

>>> from graphitequery.query import query, eval_qs
>>> print list(eval_qs("format=raw&target=*.*.*")[0])
>>> # The above is the same as:
>>> print list(query(**{"target": "*.*.*"}))


Returns a list of all leaf nodes/targets that are found in the settings.STORAGE_DIR. It doesn’t have any parameters.

Configuring graphite-query

The module graphitequery.settings can be used to set up some of the “package-wide” parameters of graphite-query. You can look into that module to see some of the supported settings. The graphitequery.query subpackage directly imports this module, so one can do a from graphitequery.query import settings for convenience.

Perhaps the most important parameter is STORAGE_DIR, the directory that is used to look for data. By default, this directory is set to /opt/graphite/storage, as this is the default directory used by graphite. You could set this parameter manually, but it’s better to use the provided graphitequery.settings.setup_storage_variables function, as this will set some additional dependant parameters (such as the whisper storage directory etc.). Otherwise, one would have to set those parameters manually also.

Finally, it’s possible to set the STORAGE_DIR parameter with the environment variable GRAPHITE_STORAGE_DIR, prior to running/importing graphite-query. This variable will trigger the setup_storage_variables function to set all of the default directories relative to (GRAPHITE_)STORAGE_DIR.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

graphite-query-0.11.3.tar.gz (50.8 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page