Package: graphite-query
Overviewgraphite-queryis a
library created fromgraphite-webin order to make some of its functionality framework neutral, i.e. to
require as little dependencies as possible.InstallationYou can installgraphite-queryby running:pip install graphite-queryYou can also download/clone the github repository, and, inside the
directory where you downloadedgraphite-queryrun:python setup.py installUsageThis package provides the functionsquery,eval_qsandget_all_leaf_nodes(all are part of thegraphitequery.querysubpackage).queryquerytakes both positional and keyword arguments, which in turn are
taken fromgraphite-web’s render APIexcept for
the graph/format arguments, which are, of course, inapplicable to
graphite-query.In short, its parameters (in positional order) are:target: required, agraphite-webcompatible path (i.e.
string), or alistof paths, seehttp://graphite.readthedocs.org/en/latest/render_api.html#targetfor
additional documentation.fromanduntil: two optional parameters that specify the
relative or absolute time period to graph. seehttp://graphite.readthedocs.org/en/latest/render_api.html#from-untiltz: optional, time zone to convert all times into. If this
parameter is not specified, thengraphitequery.query.settings.TIME_ZONEis used (if any). Finally,
system’s timezone is used ifTIME_ZONEis empty. seehttp://graphite.readthedocs.org/en/latest/render_api.html#tzA basic query might look like this:>>> from graphitequery.query import query
>>> print list(query("graphite-web.compatible.path.expression")[0])Thequeryfunctionalways(even if you supply only one target
path) returns alistof instances ofgraphitequery.query.datalib.TimeSeries, which in turn is alist-like
object whose sub-elements are the values stored by graphite (in awhisperdatabase) at particular points in time.eval_qsThis is a helper function: it takes a URL query string as a parameter.
The query string must be compatible with thegraphite-web’s render
controller.eval_qsinternally converts this string to a parameter
dictionary that can be passed on toqueryand callsquery.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": "*.*.*"}))get_all_leaf_nodesReturns alistof all leaf nodes/targets that are found in thesettings.STORAGE_DIR. It doesn’t have any parameters.Configuringgraphite-queryThe modulegraphitequery.settingscan be used to set up some of the
“package-wide” parameters ofgraphite-query. You can look into that
module to see some of the supported settings. Thegraphitequery.querysubpackage directly imports this module, so one can do afrom graphitequery.query import settingsfor convenience.Perhaps the most important parameter isSTORAGE_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 bygraphite. You could set this parameter manually, but it’s better to
use the providedgraphitequery.settings.setup_storage_variablesfunction,
as this will set some additional dependant parameters (such as thewhisperstorage directory etc.). Otherwise, one would have to set
those parameters manually also.Finally, it’s possible to set theSTORAGE_DIRparameter with the
environment variableGRAPHITE_STORAGE_DIR, prior to
running/importinggraphite-query. This variable will trigger thesetup_storage_variablesfunction to set all of the default
directories relative to(GRAPHITE_)STORAGE_DIR.