github.com/go-graphite/carbonapi@v0.17.0/README.md (about) 1 carbonapi: replacement graphite API server 2 ------------------------------------------ 3 4 [](https://travis-ci.org/go-graphite/carbonapi) 5 [](https://godoc.org/github.com/go-graphite/carbonapi) 6 7 We 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! 8 9 CarbonAPI supports a significant subset of graphite functions [see [COMPATIBILITY](COMPATIBILITY.md)]. 10 In our testing it has shown to be 5x-10x faster than requesting data from graphite-web. 11 12 For requirements see **Requirements** section below. 13 14 Installation 15 ------------ 16 17 At this moment we are building packages for CentOS 7, Rockylinux 8 (should be compatible with RHEL 8), Debian 10, Debian 11, Debian 12 (testing), Ubuntu 18.04, Ubuntu 20.04, Ubuntu 22.04. Installation guides are available on packagecloud (see the links below). 18 19 Stable versions: [Stable repo](https://packagecloud.io/go-graphite/stable/install) 20 21 Autobuilds (master, might be unstable): [Autobuild repo](https://packagecloud.io/go-graphite/autobuilds/install) 22 23 Configuration guides: [docs/configuration.md](https://github.com/go-graphite/carbonapi/blob/master/doc/configuration.md) and [example config](https://github.com/go-graphite/carbonapi/blob/master/cmd/carbonapi/carbonapi.example.yaml). 24 25 There are multiple example configurations available for different backends: [prometheus](https://github.com/go-graphite/carbonapi/blob/master/cmd/carbonapi/carbonapi.example.prometheus.yaml), [graphite-clickhouse](https://github.com/go-graphite/carbonapi/blob/master/cmd/carbonapi/carbonapi.example.clickhouse.yaml), [go-carbon](https://github.com/go-graphite/carbonapi/blob/master/cmd/carbonapi/carbonapi.example.yaml), [victoriametrics](https://github.com/go-graphite/carbonapi/blob/master/cmd/carbonapi/carbonapi.example.victoriametrics.yaml), [IRONdb](https://github.com/go-graphite/carbonapi/blob/master/cmd/carbonapi/carbonapi.example.irondb.yaml) 26 27 General information 28 ------------------- 29 30 Carbonapi can be configured by environment variables or by config file. For an example see `carbonapi.example.yaml` 31 32 `$ ./carbonapi -config /etc/carbonapi.yaml` 33 34 Request metrics will be dumped to graphite if corresponding config options are set, 35 or if the GRAPHITEHOST/GRAPHITEPORT environment variables are found. 36 37 Request data will be stored in memory (default) or in memcache. 38 39 Configuration is described in [docs](https://github.com/go-graphite/carbonapi/blob/master/doc/configuration.md) 40 41 ## Configuration by environment variables 42 43 Every parameter in config file are mapped to environment variable. I.E. 44 45 ```yaml 46 concurency: 20 47 cache: 48 # Type of caching. Valid: "mem", "memcache", "null" 49 type: "mem" 50 upstreams: 51 backends: 52 - "http://10.0.0.1:8080" 53 - "http://10.0.0.2:8080" 54 ``` 55 That config can be replaced by 56 57 ```bash 58 CARBONAPI_CONCURENCY=20 59 CARBONAPI_CACHE_TYPE=mem 60 CARBONAPI_UPSTREAMS_BACKENDS="http://10.0.0.1:8080 http://10.0.0.2:8080" 61 ``` 62 63 You should be only aware of logging: because carbonapi support a list of logger, env variables will replace 64 only first logger. 65 66 If you apply variable `LOGGER_FILE=stdout` to config: 67 68 ```yaml 69 logger: 70 - logger: "" 71 file: "stderr" 72 level: "debug" 73 encoding: "console" 74 encodingTime: "iso8601" 75 encodingDuration: "seconds" 76 - logger: "" 77 file: "carbonapi.log" 78 level: "info" 79 encoding: "json" 80 ``` 81 82 it will be equal to config: 83 84 ```yaml 85 logger: 86 - logger: "" 87 file: "stdout" # Changed only here 88 level: "debug" 89 encoding: "console" 90 encodingTime: "iso8601" 91 encodingDuration: "seconds" 92 - logger: "" 93 file: "carbonapi.log" # Not changed 94 level: "info" 95 encoding: "json" 96 ``` 97 98 Supported protocols 99 ------------------- 100 101 * `auto` - carbonapi will do it's best to determine backend's protocol. Currently it can identify only `carbonapi_v2_pb` or `carbonapi_v3_pb` 102 * `carbonapi_v2_pb`, `pb`, `pb3`, `protobuf` - carbonapi <0.11 style protocol. Supported by [go-carbon](https://github.com/go-graphite/go-carbon) and [graphite-clickhouse](https://github.com/lomik/graphite-clickhouse) older or equal version v0.11.7 103 * `carbonapi_v3_pb` - new carbonapi protocol, that supports passing metadata through. Supported by carbonzipper >=1.0.0.alpha.3, [graphite-clickhouse](https://github.com/lomik/graphite-clickhouse) newer then v0.12.0 and go-carbon newer then v0.13.0 104 * `carbonapi_v3_grpc` - grpc version of new carbonapi protocol. Currently no known implementation exists. 105 * `msgpack` - messagepack based protocol, used in graphite-web 1.1 and metrictank. It's still experimental and might contain bugs. 106 * `prometheus` - prometheus HTTP API 107 * `victoriametrics` - special version of prometheus backend to use with [VictoriaMetrics](https://github.com/VictoriaMetrics/VictoriaMetrics). 108 * `irondb` - supports reading Graphite-compatible metrics from [IRONdb](https://docs.circonus.com/irondb/) from [Circonus](https://www.circonus.com/). 109 110 111 Requirements 112 ------------ 113 114 Golang compatibility matrix: 115 116 | Golang Version | Last supported carbonapi version | 117 |----------------|----------------------------------| 118 | 1.10 | 0.10.0.1 | 119 | 1.12 | 0.12.6 | 120 | 1.16 / 1.17 | 0.15.6 | 121 | 1.18 | 0.16.0-patch2 | 122 | 1.20 | 0.16.1 | 123 124 Overall rule of thumb is that carbonapi supports last 2 major go versions. E.x. at this moment Go 1.22 and 1.21 are supported. 125 126 You can verify current versions that are being tested in [CI Configuration](https://github.com/go-graphite/carbonapi/blob/main/.github/workflows/tests.yml#L14). 127 128 CarbonAPI uses protobuf-based protocol to talk with underlying storages. For current version the compatibility list is: 129 130 1. [go-carbon](https://github.com/lomik/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` 131 2. [graphite-clickhouse](https://github.com/lomik/graphite-clickhouse) any. That's alternative storage that doesn't use Whisper. 132 3. [metrictank](https://github.com/grafana/metrictank) - supported via `msgpack` protocol. Support is not very well tested and might contain bugs. Use with cautions. Tags are not supported. 133 4. [carbonapi](https://github.com/go-graphite/carbonapi) >= 0.5. Note: starting from carbonapi 1274333ebd1fe50946cb4d51561e3e0f1060bc79 separate binary of carbonzipper is deprecated. 134 5. [carbonserver](https://github.com/grobian/carbonserver)@master (Note: you should probably switch to go-carbon in that case). 135 6. [carbonzipper](https://github.com/go-graphite/carbonzipper) >= 0.50. **Please note**, carbonzipper functionality was merged to carbonapi and it's no longer needed to run separate zipper. 136 137 Supported architectures and OSs 138 ------------------------------- 139 140 Currently building is tested regularly on amd64 (automated) and arm64 (manual) only. However from time to time, riscv64 is also tested manually. 141 142 For OS support: **Linux** is the only OS that is well tested for production usage. Theoretically nothing prevents from running carbonapi on **\*BSD**, however its not tested by developers (but bugs will be accepted and eventually fixed). Running on **macos** is supported for testing purposes but it is not tested for any production use case. Other platforms are not tested and not supported. 143 144 For any other OS or Architectures bugs **won't be actively worked on**, but PRs that fixes the OS and doesn't break any other supported platforms are more than welcome. 145 146 Some remarks on different backends 147 ---------------------------------- 148 149 For backends that uses proper database (e.x. `graphite-clickhouse`) you should set `maxBatchSize: 0` in your config file for this backend group. 150 151 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. 152 153 Tag support was only tested with `graphite-clickhouse`, however it should work with any other database. 154 155 Internal Metrics 156 ---------------------------------- 157 The internal metrics are configured inside the [graphite](https://github.com/go-graphite/carbonapi/blob/main/doc/configuration.md#graphite) subsection and sent to your destinated host on an specified interval. The metrics are: 158 159 | Metric Name | Description | 160 | ----------- | ----------- | 161 | cache_items | if caching is enabled, this metric will contain many metrics are stored in cache | 162 | cache_size | configured query cache size in bytes | 163 | request_cache_hits | how many requests were served from cache. (this is for requests to /render endpoint) | 164 | request_cache_misses | how many requests were not in cache. (this is for requests to /render endpoint) | 165 | request_cache_overhead_ns | how much time in ns it took to talk to cache (that is useful to assess if cache actually helps you in terms of latency) (this is for |requests to /render endpoint) 166 | find_requests | requests server by endpoint /metrics/find | 167 | requests | requests served by endpoint /render | 168 | requests_in_XX_to_XX | request response times in percentiles | 169 | timeouts | number of timeouts while fetching from backend | 170 | backend_cache_hits | how many requests were not read from backend | 171 | backend_cache_misses | how many requests were not found in the backend | 172 173 OSX Build Notes 174 --------------- 175 Some additional steps may be needed to build carbonapi with cairo rendering on MacOSX. 176 177 Install cairo: 178 179 ``` 180 $ brew install Caskroom/cask/xquartz 181 182 $ brew install cairo --with-x11 183 ``` 184 185 Acknowledgement 186 --------------- 187 This program was originally developed for Booking.com. With approval 188 from Booking.com, the code was generalised and published as Open Source 189 on github, for which the author would like to express his gratitude. 190 191 Booking.com's Fork 192 ------------------ 193 194 In summer 2018, Booking.com forked version 0.11 of carbonapi and continued development in their own repo: [github.com/bookingcom/carbonapi](https://github.com/bookingcom/carbonapi). 195 196 License 197 ------- 198 199 This code is licensed under the BSD-2 license.