README.md
1carbonzipper: carbonserver proxy for graphite-web
2=================================================
3
4[](https://travis-ci.org/go-graphite/carbonzipper)
5
6We are using <a href="https://packagecloud.io/"><img alt="Private Maven, RPM, DEB, PyPi and RubyGem Repository | packagecloud" height="46" src="https://packagecloud.io/images/packagecloud-badge.png" width="158" /></a> to host our packages!
7
8CarbonZipper is the central part of a replacement graphite storage stack. It
9proxies requests from graphite-web to a cluster of carbon storage backends.
10Previous versions (available in the git history) were able to talk to python
11carbon stores, but the current version requires the use of
12[go-carbon](https://github.com/lomik/go-carbon) or [graphite-clickhouse](https://github.com/lomik/graphite-clickhouse).
13
14
15Installation
16------------
17
18Stable versions: [Stable repo](https://packagecloud.io/go-graphite/stable/install)
19
20Autobuilds (master, might be unstable): [Autobuild repo](https://packagecloud.io/go-graphite/autobuilds/install)
21
22General information
23-------------------
24Configuration is done via a YAML file loaded at startup. The only required
25field is the list of carbonserver backends to connect to.
26
27Other pieces of the stack are:
28 - [carbonapi](https://github.com/go-graphite/carbonapi)
29 - [carbonmem](https://github.com/go-graphite/carbonmem)
30 - [carbonsearch](https://github.com/kanatohodets/carbonsearch)
31
32For an overview of the stack and how the pieces fit together, watch
33[Graphite@Scale or How to store millions metrics per second](https://fosdem.org/2017/schedule/event/graphite_at_scale/)
34from FOSDEM '17 or [Graphite@Scale or How to Store Millions of metrics per Second](https://www.usenix.org/conference/srecon17asia/program/presentation/smirnov) from SRECon17 Asia.
35
36Requirements
37------------
38
39carbonzipper requires Go 1.8+ to build. It's recommended to always use latest stable.
40
41CarbonZipper uses protobuf-based protocol to talk with underlying storages. For current version the compatibility list is:
42
431. [carbonzipper](https://github.com/go-graphite/carbonzipper) >= 0.50
442. [go-carbon](https://github.com/lomik/go-carbon) >= 0.9.0 (Note: you need to enable carbonserver in go-carbon).
453. [carbonserver](https://github.com/grobian/carbonserver)@master (Note: you should probably switch to go-carbon in that case).
464. [graphite-clickhouse](https://github.com/lomik/graphite-clickhouse) any. That's alternative storage that doesn't use Whisper. Limitations: /info handler won't work properly.
475. [carbonapi](https://github.com/go-graphite/carbonapi) >= 0.5. Note: we are not sure if there is any point in running carbonzipper over carbonapi at this moment.
48
49Changes and versioning
50----------------------
51
52Version policy - all the versions we run in production is taged.
53
54In case change will require simultanious upgrade of different components, it will be stated in Upgrading notes below.
55
56Also we will try to maintain backward compatibility from down to up.
57
58For example with protobuf2 -> protobuf3 migration - carbonzipper can still send results to older versions of carbonapi, but can't get results from older versions of carbonserver/go-carbon.
59
60See [CHANGES.md](https://github.com/go-graphite/carbonzipper/blob/master/CHANGES.md)
61
62Upgrading to 0.60 from 0.50 or earlier
63--------------------------------------
64
65Starting from 0.60, carbonzipper will be able to talk **only** with storages compatible with **protobuf3**.
66
67At this moment (0.60) it's only go-carbon, starting from commit ee2bc24 (post 0.9.1)
68
69Carbonzipper can still return results in protobuf and compatibility won't be removed at least until Summer 2017.
70
71If you want to upgrade, the best option is to do follwing steps:
72
731. Migrate to go-carbon post 0.9.1 release. (note: carbonserver isn't compatible with this version of zipper)
742. Migrate to carbonsearch 0.16.0 (if you are using any)
753. Upgrade carbonzipper to 0.60 or newer.
764. Upgrade carbonapi to 0.6.0 (commit 119e346 or newer) (optional, but advised)
77
78
79Acknowledgement
80---------------
81This program was originally developed for Booking.com. With approval
82from Booking.com, the code was generalised and published as Open Source
83on github, for which the author would like to express his gratitude.
84
85License
86-------
87
88This code is licensed under the MIT license.
89
90
91Contact
92-------
93
94If you have questions or problems there are two ways to contact us:
95
961. Open issue on a github page
972. #zipperstack on [gophers slack](https://invite.slack.golangbridge.org/)
98
){kind=link}
