gographite/carbonapi

carbonapi：替代Graphite API服务器

镜像概述和主要用途

carbonapi是一个用Go语言重实现的Graphite API服务器，旨在替代传统的graphite-web，提供更高效的数据查询服务。它支持Graphite函数的大部分子集，在测试中表现出比graphite-web快5-10倍的性能。该镜像适用于需要高性能时序数据查询的监控场景，可与多种后端存储集成。

注意：原仓库已弃用，所有新的Docker容器均推送至ghcr.io/go-graphite/carbonapi。

核心功能和特性

• 高性能：查询速度比graphite-web快5-10倍
• 函数兼容性：支持大部分Graphite函数（详见https://github.com/go-graphite/carbonapi/blob/master/COMPATIBILITY.md%EF%BC%89
• 多后端支持：兼容多种存储后端（go-carbon、graphite-clickhouse、metrictank等）
• 灵活配置：支持通过配置文件或环境变量进行配置
• 缓存机制：支持内存、memcache等缓存方式存储请求数据
• 多协议支持：支持auto、carbonapi_v2_pb、carbonapi_v3_pb、msgpack、prometheus等多种协议

使用场景和适用范围

• 替代graphite-web作为Graphite生态系统的API查询层
• 需要高性能时序数据查询的监控平台
• 与go-carbon、graphite-clickhouse等现代存储后端配合使用
• 对Graphite函数兼容性有较高要求的场景

详细使用方法和配置说明

安装方式

目前提供适用于以下系统的安装包：CentOS 6/7、Debian 9/10、Ubuntu 14.04/16.04/18.04。

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

配置指南

carbonapi可通过配置文件或环境变量进行配置。

配置文件示例

配置文件示例可参考：

• https://github.com/go-graphite/carbonapi/blob/master/cmd/carbonapi/carbonapi.example.yaml
• https://github.com/go-graphite/carbonapi/blob/master/cmd/carbonapi/carbonapi.example.prometheus.yaml
• https://github.com/go-graphite/carbonapi/blob/master/cmd/carbonapi/carbonapi.example.clickhouse.yaml
• https://github.com/go-graphite/carbonapi/blob/master/cmd/carbonapi/carbonapi.example.yaml

完整配置说明见https://github.com/go-graphite/carbonapi/blob/master/doc/configuration.md%E3%80%82

环境变量配置

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

配置文件方式：

yaml
concurency: 20
cache:
  # 缓存类型，可选："mem", "memcache", "null"
  type: "mem"
upstreams:
  backends:
    - "http://10.0.0.1:8080"
    - "http://10.0.0.2:8080"

环境变量方式：

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

注意：日志配置中，环境变量仅会替换第一个日志记录器的配置。

Docker部署示例

docker run命令

bash
docker run -d \
  --name carbonapi \
  -p 8080:8080 \
  -v /path/to/carbonapi.yaml:/etc/carbonapi.yaml \
  ghcr.io/go-graphite/carbonapi \
  -config /etc/carbonapi.yaml

docker-compose配置

yaml
version: '3'
services:
  carbonapi:
    image: ghcr.io/go-graphite/carbonapi
    container_name: carbonapi
    ports:
      - "8080:8080"
    volumes:
      - ./carbonapi.yaml:/etc/carbonapi.yaml
    command: -config /etc/carbonapi.yaml
    environment:
      - CARBONAPI_CONCURENCY=20
      - CARBONAPI_CACHE_TYPE=mem
      - CARBONAPI_UPSTREAMS_BACKENDS="http://go-carbon:8080"

支持的协议

• auto：自动检测后端协议（目前仅支持carbonapi_v2_pb或carbonapi_v3_pb）
• carbonapi_v2_pb/pb/pb3/protobuf：carbonapi <0.11版本协议，支持go-carbon、graphite-clickhouse
• carbonapi_v3_pb：新版carbonapi协议，支持元数据传递，需carbonzipper >=1.0.0.alpha.3
• carbonapi_v3_grpc：gRPC版新版协议，目前无已知实现
• msgpack：基于messagepack的协议，用于graphite-web 1.1和metrictank（实验性，可能存在bug）
• prometheus：Prometheus HTTP API

系统要求

• 构建源码需Go >= 1.14（0.11.0起不支持Go 1.10及更早版本，0.13.0起不支持Go 1.12及更早版本）
• 后端兼容性列表：
  1. go-carbon >= 0.9.0（需启用carbonserver，推荐最新版本以支持carbonapi_v3_pb）
  2. graphite-clickhouse（任何版本）
  3. metrictank（通过msgpack协议，支持有限，不支持标签，需谨慎使用）
  4. carbonapi >= 0.5（自0.8版本后可作为carbonzipper替代品）
  5. carbonserver@master（建议切换到go-carbon）
  6. carbonzipper >= 0.50（功能已合并到carbonapi，无需单独运行）

不同后端的注意事项

• 对于使用数据库的后端（如graphite-clickhouse），应在配置中将该后端组的maxBatchSize设置为0
• 对于其他后端（如go-carbon），应将maxBatchSize设置为合理值以提高响应速度（代价是增加内存消耗）
• 标签支持仅在graphite-clickhouse上测试过，但理论上可与其他数据库兼容

许可

本代码采用BSD-2许可协议。

鸣谢

该程序最初为Booking.com开发，经Booking.com批准后作为开源项目发布。

Booking.com的分叉版本

2018年夏季，Booking.com分叉了carbonapi 0.11版本并在其自己的仓库中继续开发：https://github.com/bookingcom/carbonapi%E3%80%82