carbonapi

carbonapi: 替代性的graphite API服务器

我们使用 <a href="https://packagecloud.io/"><img alt="私有Maven、RPM、DEB、PyPi和RubyGem仓库 | packagecloud" height="46" src="https://yellow-cdn.veclightyear.com/0a4dffa0/38354313-4250-413b-a67b-15d24f3d8d24.png" width="158" /></a> 来托管我们的软件包！

CarbonAPI支持大部分graphite函数[参见 [兼容性](https://github.com/go-graphite/carbonapi/blob/main/COMPATIBILITY.md]。 在我们的测试中，它比从graphite-web请求数据快5-10倍。

关于需求，请参见下面的需求部分。

安装

目前我们正在为CentOS 7、Rockylinux 8（应与RHEL 8兼容）、Debian 10、Debian 11、Debian 12（测试版）、Ubuntu 18.04、Ubuntu 20.04、Ubuntu 22.04构建软件包。安装指南可在packagecloud上获取（见下方链接）。

稳定版本：稳定版仓库

自动构建版本（master分支，可能不稳定）：自动构建仓库

配置指南：docs/configuration.md 和 示例配置。

有多个针对不同后端的示例配置可用：prometheus、graphite-clickhouse、go-carbon、victoriametrics、IRONdb

一般信息

Carbonapi可以通过环境变量或配置文件进行配置。示例请参见carbonapi.example.yaml

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

如果设置了相应的配置选项，或者找到GRAPHITEHOST/GRAPHITEPORT环境变量，请求指标将被转储到graphite。

请求数据将存储在内存（默认）或memcache中。

配置说明见文档

通过环境变量进行配置

配置文件中的每个参数都映射到环境变量。例如：

concurency: 20
cache:
   # 缓存类型。有效值："mem"、"memcache"、"null"
   type: "mem"
upstreams:
    backends:
        - "http://10.0.0.1:8080"
        - "http://10.0.0.2:8080"

该配置可以替换为

CARBONAPI_CONCURENCY=20
CARBONAPI_CACHE_TYPE=mem
CARBONAPI_UPSTREAMS_BACKENDS="http://10.0.0.1:8080 http://10.0.0.2:8080"

你只需注意日志记录：因为carbonapi支持记录器列表，环境变量只会替换第一个记录器。

如果你将变量LOGGER_FILE=stdout应用到配置：

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

它将等同于配置：

logger:
    - logger: ""
      file: "stdout" # 只在这里改变
      level: "debug"
      encoding: "console"
      encodingTime: "iso8601"
      encodingDuration: "seconds"
    - logger: ""
      file: "carbonapi.log" # 未改变
      level: "info"
      encoding: "json"

支持的协议

• auto - carbonapi将尽最大努力确定后端的协议。目前它只能识别carbonapi_v2_pb或carbonapi_v3_pb
• carbonapi_v2_pb、pb、pb3、protobuf - carbonapi <0.11风格协议。由go-carbon和graphite-clickhouse版本小于等于v0.11.7支持
• carbonapi_v3_pb - 新的carbonapi协议，支持传递元数据。由carbonzipper >=1.0.0.alpha.3、graphite-clickhouse新于v0.12.0和go-carbon新于v0.13.0支持
• carbonapi_v3_grpc - 新carbonapi协议的grpc版本。目前没有已知的实现存在。
• msgpack - 基于messagepack的协议，用于graphite-web 1.1和metrictank。它仍处于实验阶段，可能包含错误。
• prometheus - prometheus HTTP API
• victoriametrics - 专门用于VictoriaMetrics的prometheus后端版本。
• irondb - 支持从Circonus的IRONdb读取兼容Graphite的指标。

需求

Golang兼容性矩阵：

Golang版本	最后支持的carbonapi版本
1.10	0.10.0.1
1.12	0.12.6
1.16 / 1.17	0.15.6
1.18	0.16.0-patch2
1.20	0.16.1

总的来说，carbonapi支持最后两个主要的go版本。例如，目前支持Go 1.22和1.21。

你可以在CI配置中验证当前正在测试的版本。

CarbonAPI使用基于protobuf的协议与底层存储通信。对于当前版本，兼容性列表如下：

1. go-carbon >= 0.9.0（注意：你需要在go-carbon中启用carbonserver）。建议运行最新版本，当前支持carbonapi_v3_pb。
2. graphite-clickhouse 任何版本。这是一个不使用Whisper的替代存储方案。
3. metrictank - 通过msgpack协议支持。支持尚未经过充分测试，可能存在bugs。请谨慎使用。不支持标签。
4. carbonapi >= 0.5。注意：从carbonapi 1274333ebd1fe50946cb4d51561e3e0f1060bc79版本开始，单独的carbonzipper二进制文件已被弃用。
5. carbonserver@master（注意：在这种情况下，你可能应该切换到go-carbon）。
6. carbonzipper >= 0.50。请注意，carbonzipper的功能已合并到carbonapi中，不再需要运行单独的zipper。

支持的架构和操作系统

目前，构建仅在amd64（自动）和arm64（手动）上定期测试。但是，riscv64也会不时进行手动测试。

对于操作系统支持：Linux是唯一经过充分测试可用于生产环境的操作系统。理论上没有什么阻止carbonapi在***BSD上运行，但开发人员并未对其进行测试（但会接受并最终修复bugs）。在macOS**上运行仅支持测试目的，但未针对任何生产用例进行测试。其他平台未经测试且不受支持。

对于任何其他操作系统或架构，bugs不会被积极处理，但欢迎提交不破坏任何其他受支持平台的修复PR。

关于不同后端的一些注意事项

对于使用适当数据库的后端（例如graphite-clickhouse），你应该在配置文件中为该后端组设置maxBatchSize: 0。

对于其他后端（例如go-carbon），你应该将其设置为一个合理的值。这会提高响应速度，但代价是增加内存消耗。

标签支持仅在graphite-clickhouse上进行了测试，但应该可以与任何其他数据库一起使用。

内部指标

内部指标在graphite子部分中配置，并按指定间隔发送到你指定的主机。这些指标包括：

指标名称	描述
cache_items	如果启用了缓存，此指标将包含缓存中存储的指标数量
cache_size	配置的查询缓存大小（字节）
request_cache_hits	从缓存中提供的请求数（针对/render端点的请求）
request_cache_misses	不在缓存中的请求数（针对/render端点的请求）
request_cache_overhead_ns	与缓存通信所花费的时间（纳秒）（用于评估缓存在延迟方面是否真正有帮助）（针对/render端点的请求）
find_requests	/metrics/find端点处理的请求数
requests	/render端点处理的请求数
requests_in_XX_to_XX	请求响应时间百分位数
timeouts	从后端获取数据时的超时次数
backend_cache_hits	未从后端读取的请求数
backend_cache_misses	在后端未找到的请求数

OSX构建注意事项

在MacOSX上使用cairo渲染构建carbonapi可能需要一些额外步骤。

安装cairo：

$ brew install Caskroom/cask/xquartz

$ brew install cairo --with-x11

致谢

该程序最初是为Booking.com开发的。经Booking.com批准，代码被泛化并作为开源项目发布在github上，作者对此表示感谢。

Booking.com的分支

2018年夏天，Booking.com从carbonapi的0.11版本分叉，并在他们自己的仓库中继续开发：github.com/bookingcom/carbonapi。

许可证

本代码采用BSD-2许可证授权。