Vladimir Smirnov 7b70cdb03a
Merge pull request #317 from go-graphite/gmagnusson/timeShift
5 days ago
carbonapipb Migrate timestamps to int64 and fix tests 1 month ago
contrib add log directory and logrotate config 2 months ago
date Migrate timestamps to int64 and fix tests 1 month ago
doc/development Update docs/development/functions 2 months ago
expr Write some tests for sumSeries 5 days ago
internal Bunch of fixes related to tests and code refactoring 2 months ago
pkg/parser Migrate timestamps to int64 and fix tests 1 month ago
scripts Refactor functions again 2 months ago
tests Migrate timestamps to int64 and fix tests 1 month ago
util Changes from code review comments. 5 months ago
vendor Update zipper 1 month ago
.codacy.yaml Adding codacy config file for better control of codacy checks. (#266) 6 months ago
.gitignore Update Changelog and gitignore 3 months ago
.travis.yml Update bundled carbonzipper and enable back autobuilds 1 month ago
BUILD.md Update README 1 year ago
CHANGES.md Update changelog 1 month ago
COMPATIBILITY.md Update COMPATIBILITY.md to list some of functions that was added in graphite-web 1.1 2 months ago
Gopkg.lock Update zipper 1 month ago
Gopkg.toml Update vendored deps. This *will* break the build 1 month ago
LICENSE add LICENSE file 2 years ago
Makefile Bunch of fixes related to tests and code refactoring 2 months ago
README.md Update changelog 1 month ago
carbonapi.example.toml Add support for msgpack backends 1 month ago
carbonapi.example.yaml Add support for msgpack backends 1 month ago
graphTemplates.example.toml Fix config parsing and update readme and examples 1 month ago
graphTemplates.example.yaml Fix config parsing and update readme and examples 1 month ago
graphiteWeb.example.yaml Add parameter nativeOnly to /functions api 2 months ago
http_handlers.go Fix issue with matching of request to responses where from and until interval can change depending upon the expression requested. Fixes the issues by matching request time interval (with offset) to response time interval. 1 week ago
limiter.go limiter.go: limiter is in package main and NewLimiter should be private anyway - unexport. [golint] 1 year ago
main.go Various bugfixes 1 month ago
main_test.go Fix tests 1 month ago
zipper.go Various bugfixes 1 month ago


carbonapi: replacement graphite API server

Build Status GoDoc PR Stats Issues Stats

We are using to host our packages!

CarbonAPI supports a significant subset of graphite functions [see COMPATIBILITY]. In our testing it has shown to be 5x-10x faster than requesting data from graphite-web.

For requirements see Requirements section below.


At this moment we are building packages for CentOS 6, CentOS 7, Ubuntu 14.04 and Ubuntu 16.04. Installation guides are available on packagecloud (see the links below).

Stable versions: Stable repo

Autobuilds (master, might be unstable): Autobuild repo

General information

Carbonzipper can be configured by environment variables or by config file. For an example see carbonapi.example.yaml

$ ./carbonapi -config /etc/carbonapi.yaml

Request metrics will be dumped to graphite if coresponding config options are set, or if the GRAPHITEHOST/GRAPHITEPORT environment variables are found.

Request data will be stored in memory (default) or in memcache.

Configuration by environment variables

Every parameter in config file are mapped to environment variable. I.E.

concurency: 20
   # Type of caching. Valid: "mem", "memcache", "null"
   type: "mem"
        - ""
        - ""

That config can be replaced by


You should be only aware of logging: because carbonapi support a list of logger, env variables will replace only first logger.

If you apply variable LOGGER_FILE=stdout to config:

    - logger: ""
      file: "stderr"
      level: "debug"
      encoding: "console"
      encodingTime: "iso8601"
      encodingDuration: "seconds"
    - logger: ""
      file: "carbonapi.log"
      level: "info"
      encoding: "json"

it will be equal to config:

    - logger: ""
      file: "stdout" # Changed only here
      level: "debug"
      encoding: "console"
      encodingTime: "iso8601"
      encodingDuration: "seconds"
    - logger: ""
      file: "carbonapi.log" # Not changed
      level: "info"
      encoding: "json"

Supported protocols

  • auto - carbonapi will do it's best to determine backend's protocol. Currently it can identify only carbonapi_v2_pb or carbonapi_v3_pb
  • carbonapi_v2_pb, pb, pb3, protobuf - carbonapi pre-0.12 style protocol. Supoorted by go-carbon, graphite-clickhouse, etc.
  • carbonapi_v3_pb - new carbonapi protocol, that supports passing metadata through. Supported by carbonzipper 1.0.0.alpha.3 or later. Implementing support for that is in-progress for go-carbon and graphite-clickhouse
  • carbonapi_v3_grpc - grpc version of new carbonapi protocol. Currently no known implementation exists.
  • msgpack - messagepack based protocol, used in graphite-web 1.1 and metrictank. It's still experimental and might contain bugs.


You need to have Go >= 1.8 to build carbonapi from sources. Building with Go 1.7 is not supported for versions >0.8.0

CarbonAPI uses protobuf-based protocol to talk with underlying storages. For current version the compatibility list is:

  1. go-carbon >= 0.9.0 (Note: you need to enable carbonserver in go-carbon). Recommended to run latest version, that currently supports carbonapi_v3_pb
  2. graphite-clickhouse any. That's alternative storage that doesn't use Whisper.
  3. metrictank - supported via msgpack protocol. Support is not very well tested and might contain bugs. Use with cautions. Tags are not supported.
  4. carbonapi >= 0.5. Note: starting from carbonapi 3596e96476 (post 0.8) carbonapi can be used as a zipper's replacement
  5. carbonserver@master (Note: you should probably switch to go-carbon in that case).
  6. carbonzipper >= 0.50. Please note, carbonzipper functionality was merged to carbonapi and it's no longer needed to run separate zipper.

Some remarks on different backends

For backends that uses normal database (e.x. graphite-clickhouse) you should set maxGlobs: 0 in your config file for this backend group.

For other backends (e.x. go-carbon) you should set it to some reasonable value. It increases response speed, but the cost is increased memory consumption.

OSX Build Notes

Some additional steps may be needed to build carbonapi with cairo rendering on MacOSX.

Install cairo:

$ brew install Caskroom/cask/xquartz

$ brew install cairo --with-x11


This program was originally developed for Booking.com. With approval from Booking.com, the code was generalised and published as Open Source on github, for which the author would like to express his gratitude.


This code is licensed under the BSD-2 license.