Configuration

Configuration File Location

The configuration file for Graphite-Render uses the YAML format. Creating the configuration file is optional: if Graphite-Render doesn’t find a configuration file, sane defaults are used.

Graphite-Render searches for configuration files in the following order:

  1. /etc/graphite-render.yaml (or the path specified in the GRAPHITE_API_CONFIG environment variable)

  2. /etc/graphite-api.yml (fallback for compatibility with graphite-api)

If neither file is found, Graphite-Render uses default configuration values described below.

Default values

search_index: /srv/graphite/index
finders:
  - graphite_render.finders.whisper.WhisperFinder
functions:
  - graphite_render.functions.SeriesFunctions
  - graphite_render.functions.PieFunctions
whisper:
  directories:
    - /srv/graphite/whisper
time_zone: <system timezone> or UTC

Config sections

Default sections

search_index

The location of the search index used for searching metrics. Note that it needs to be a file that is writable by the Graphite-Render process.

finders

A list of python paths to the storage finders you want to use when fetching metrics.

functions

A list of python paths to function definitions for transforming / analyzing time series data.

whisper

The configuration information for whisper. Only relevant when using WhisperFinder. Simply holds a directories key listing all directories containing whisper data.

time_zone

The time zone to use when generating graphs. By default, Graphite-Render tries to detect your system timezone. If detection fails it falls back to UTC. You can also manually override it if you want another value than your system’s timezone.

Extra sections

carbon

Configuration information for reading data from carbon’s cache. Items:

hosts

List of carbon-cache hosts, in the format hostname:port[:instance].

timeout

Socket timeout for carbon connections, in seconds.

retry_delay

Time to wait before trying to re-establish a failed carbon connection, in seconds.

hashing_keyfunc

Python path to a hashing function for metrics. If you use Carbon with consistent hashing and a custom function, you need to point to the same hashing function.

hashing_type

Type of metric hashing function. The default carbon_ch is Graphite’s traditional consistent-hashing implementation. Alternatively, you can use fnv1a_ch, which supports the Fowler-Noll-Vo hash function (FNV-1a) hash implementation offered by the carbon-c-relay project. Default: carbon_ch

carbon_prefix

Prefix for carbon’s internal metrics. When querying metrics starting with this prefix, requests are made to all carbon-cache instances instead of one instance selected by the key function. Default: carbon.

replication_factor

The replication factor of your carbon setup. Default: 1.

Example:

carbon:
  hosts:
    - 127.0.0.1:7002
  timeout: 1
  retry_delay: 15
  carbon_prefix: carbon
  replication_factor: 1

sentry_dsn

This is useful if you want to send Graphite-Render’s exceptions to a Sentry instance for easier debugging.

Example:

sentry_dsn: https://key:secret@app.getsentry.com/12345

Note

Sentry integration requires Graphite-Render to be installed with the corresponding extra dependency:

$ pip install graphite-render[sentry]

allowed_origins

Allows you to do cross-domain (CORS) requests to the Graphite API. Say you have a dashboard at dashboard.example.com that makes AJAX requests to graphite.example.com, just set the value accordingly:

allowed_origins:
  - dashboard.example.com

You can specify as many origins as you want. A wildcard can be used to allow all origins:

allowed_origins:
  - *

cache

Lets you configure a cache for graph rendering. This is done via Flask-Cache which supports a number of backends including memcache, Redis, filesystem or in-memory caching.

Cache configuration maps directly to Flask-Cache’s config values. For each CACHE_* config value, set the lowercased name in the cache section, without the prefix. Example:

cache:
  type: redis
  redis_host: localhost

This would configure Flask-Cache with CACHE_TYPE = 'redis' and CACHE_REDIS_HOST = 'localhost'.

Some cache options have default values defined by Graphite-Render:

  • default_timeout: 60

  • key_prefix: 'graphite-render:.

Note

Caching functionality requires you to install the cache extra dependency but also the underlying driver. E.g. for redis, you’ll need:

$ pip install graphite-render[cache] redis

statsd

Attaches a statsd object to the application, which can be used for instrumentation. Currently Graphite-Render itself doesn’t use this, but some backends do, like Graphite-Influxdb.

Example:

statsd:
    host: 'statsd_host'
    port: 8125  # not needed if default

Note

This requires the statsd module:

$ pip install statsd

render_errors

If True (default), full tracebacks are returned in the HTTP response in case of application errors.

Custom location

If you need the Graphite-Render config file to be stored in another place than /etc/graphite-render.yaml, you can set a custom location using the GRAPHITE_API_CONFIG environment variable:

export GRAPHITE_API_CONFIG=/var/lib/graphite/config.yaml