# Configuration

## /etc/graphite-api.yaml

The configuration file for Graphite-API lives at `/etc/graphite-api.yaml` and uses the YAML format. Creating the configuration file is optional: if Graphite-API doesn’t find the file, sane defaults are used. They are described below.

### Default values

    search_index: /srv/graphite/index
    finders:
      - graphite_api.finders.whisper.WhisperFinder
    functions:
      - graphite_api.functions.SeriesFunctions
      - graphite_api.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-API 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-API 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.
> 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-API’s exceptions to a Sentry instance for easier debugging.

> Example:

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

> Note

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

>     $ pip install graphite-api[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-API:

> - `default_timeout`: 60
> - `key_prefix`: `'graphite-api:`.

> 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-api[cache] redis

statsd

> Attaches a statsd object to the application, which can be used for instrumentation. Currently Graphite-API 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-API config file to be stored in another place than `/etc/graphite-api.yaml`, you can set a custom location using the `GRAPHITE_API_CONFIG` environment variable:

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