Graphite 1.1.10 配置参数详解

carbon.conf 三段核心参数（cache 写入与流控、relay 分片、aggregator 预聚合）、storage-schemas 保留策略与 first-match 顺序陷阱排障实录、storage-aggregation 聚合实测、local_settings.py 环境变量全表与生产配置模板。

GraphiteGraphite监控2026/10/20

Graphite 1.1.10 配置参数详解

目标：系统讲清 Graphite 1.1.10 三大配置面——carbon.conf（carbon 守护进程）、storage-schemas.conf / storage-aggregation.conf（whisper 保留与聚合策略）、graphite-web 的 local_settings.py——每个核心参数给出默认值、含义与改动影响，并对关键结论（schema 匹配顺序、重启生效方式、自定义 schema 验证）在 Ubuntu 22.04.4 + graphiteapp/graphite-statsd 1.1.10-5 环境实测验证。

一、环境信息

  • 操作系统：Ubuntu 22.04.4 LTS
  • Graphite：graphite-web / carbon / whisper 1.1.10，官方一体化镜像 graphiteapp/graphite-statsd:1.1.10-5（部署方式见《Graphite 1.1.10 Docker Compose 部署指南》，配置目录挂载于宿主 /opt/graphite-deploy/graphite/conf，对应容器内 /opt/graphite/conf）
  • 实测端口：carbon 明文 2003、pickle 2004、carbonlink 7002、statsd UDP 8125、Web 80/8080
  • 验证工具：whisper-info.py（查看归档）、nc（打点）、validate-storage-schemas.py（配置校验）

二、前置条件

已按《Graphite 1.1.10 Docker Compose 部署指南》完成部署且栈为 healthy 状态：

docker compose ps

实测回显（节选）：

NAME                  IMAGE                                ...  STATUS
graphite-1.1.10-web   graphiteapp/graphite-statsd:1.1.10-5 ...  Up X seconds (healthy)

配置文件查看与编辑直接在宿主挂载目录进行（容器内 /opt/graphite/conf 与宿主 ./graphite/conf 同源）：

ls /opt/graphite-deploy/graphite/conf/

实测回显：

aggregation-rules.conf  blacklist.conf  carbon.amqp.conf  carbon.conf
dashboard.conf  go-carbon.conf  graphTemplates.conf  relay-rules.conf
rewrite-rules.conf  storage-aggregation.conf  storage-schemas.conf  whitelist.conf

三、参数查看与修改方式

3.1 三层配置体系

配置文件生效对象修改后生效方式
carbon.confcarbon-cache / carbon-relay / carbon-aggregator 守护进程重启对应 carbon 进程（一体化镜像即重启容器内服务或整个栈）
storage-schemas.conf新建的 whisper 文件归档结构（对已存在文件不追溯生效）carbon 热加载（官方注释：每 60 秒扫描变更），稳妥做法是重启；存量文件需 whisper-resize.py 迁移
storage-aggregation.confwhisper 文件头中的聚合方法（创建时写入，不追溯）同上
local_settings.pygraphite-web（Django）重启 Web（gunicorn）进程
relay-rules.conf / aggregation-rules.conf / rewrite-rules.confcarbon-relay / carbon-aggregator对应守护进程重启

⚠️ 注意：storage-schemas 与 storage-aggregation 只在 whisper 文件创建时读取匹配一次，写入文件头。修改保留策略对已有 .wsp 文件无效——要么删除重建（丢历史数据），要么用 whisper-resize.py / whisper-auto-resize.py 迁移。

3.2 修改 → 重启 → 验证的标准流程

以本文 4.2 节的实测为例，全流程为：

  1. 编辑 /opt/graphite-deploy/graphite/conf/<目标>.conf；
  2. 语法/合法性校验（schema 类配置）：/opt/graphite/bin/validate-storage-schemas.py /opt/graphite/conf/storage-schemas.conf，实测回显：
Loading storage-schemas configuration from: '/opt/graphite/conf/storage-schemas.conf'
Section 'carbon':
  OK
Section 'default_1min_for_1day':
  OK
Storage-schemas configuration '/opt/graphite/conf/storage-schemas.conf' is valid
  1. 重启服务：docker compose restart graphite；
  2. 打一个全新指标名并用 whisper-info.py 验证归档结构（见 4.2 实测）。

四、carbon.conf 核心参数详解

carbon.conf 是 INI 格式，分 [cache]（carbon-cache）、[relay]（carbon-relay）、[aggregator]（carbon-aggregator）三个段，其余段按 [实例名:段名] 形式做多实例覆盖。以下为 1.1.10 默认生效值（实测读取自 /opt/graphite/conf/carbon.conf，已剔除注释行）。

4.1 [cache] 段——carbon-cache（最常用）

4.1.1 存储与写入性能

参数默认值含义与影响
DATABASEwhisper存储引擎，可换 cassandra（Cassandra 缓存层实验特性）
MAX_CACHE_SIZEinf内存指标缓存上限（条数）。inf 表示不限制（依赖 USE_FLOW_CONTROL 反压）；峰值流量大的实例建议设为具体值（如 1000000）防内存失控
MAX_UPDATES_PER_SECOND500whisper 每秒写盘更新上限。磁盘强可上调（如 1000），写满瓶颈时指标积压
MAX_CREATES_PER_MINUTE50每分钟新建 .wsp 文件上限。新指标洪峰（新服务上线）会被限流并丢弃，扩容场景可调大
MIN_TIMESTAMP_RESOLUTION1接受的最小时间戳分辨率（秒）
CACHE_WRITE_STRATEGYsorted缓存刷盘排序：sorted（时间桶排序写，磁盘友好）、naive（先到先写）、timesorted（桶内保序）
WHISPER_AUTOFLUSHFalseTrue 时每收到一点立即 fsync，强一致但性能差；默认 False 走缓存批量刷
WHISPER_FALLOCATE_CREATEFalse新建文件时用 fallocate 预分配，ext4 上可提升创建速度
USE_FLOW_CONTROLTrue缓存达到 MAX_CACHE_SIZE 比例时暂停接收（2003 返回流控），保护内存

4.1.2 监听端口

参数默认值含义
LINE_RECEIVER_INTERFACE / PORT0.0.0.0 / 2003明文行协议接收地址/端口（metric value timestamp\n）
ENABLE_UDP_LISTENER / UDP_RECEIVER_PORTFalse / 2003明文协议 UDP 接收开关
PICKLE_RECEIVER_INTERFACE / PORT0.0.0.0 / 2004pickle 批量协议接收（批量打点性能更高）
USE_INSECURE_UNPICKLERFalseTrue 允许不安全 pickle（仅在可信内网评估）
CACHE_QUERY_INTERFACE / PORT0.0.0.0 / 7002carbonlink 缓存查询口（graphite-web 补取未落盘点）

4.1.3 自监控与标签

参数默认值含义
CARBON_METRIC_INTERVAL10carbon 自监控指标（carbon.agents.*）上报周期（秒）
ENABLE_TAGSTrue启用 tag 索引（TagDB）
LOG_UPDATES / LOG_CREATES / LOG_CACHE_HITSFalse对应调试日志开关（写 updates.log / creates.log / cache.log）
ENABLE_LOGROTATIONTruecarbon 自带日志轮转

实测：将 LOG_CREATES = False 改为 True 并重启，新指标创建即记录调试日志；carbon.agents.graphite-server-a.metricsReceived 等自监控指标以 10 秒间隔落盘（render API 可查到递增序列）。

4.2 [relay] 段——carbon-relay（分片路由）

参数默认值含义
LINE_RECEIVER_PORT / PICKLE_RECEIVER_PORT2013 / 2014relay 的接收端口（注意与 cache 的 2003/2004 区分）
RELAY_METHODrules分片方式：rules（按 relay-rules.conf 正则路由）、consistent-hashing（一致性哈希，配合 REPLICATION_FACTOR）、aggregated-hashing
REPLICATION_FACTOR1哈希分片下每指标副本数
DESTINATIONS127.0.0.1:2004下游 carbon-cache 列表（host:port:instance）
MAX_QUEUE_SIZE10000每目的地队列上限（条）
MAX_DATAPOINTS_PER_MESSAGE500每个下游 pickle 包最大点数
USE_FLOW_CONTROLTrue下游慢时反压
USE_RATIO_RESET / MIN_RESET_*False / 121 等队列积压比例重置哈希一致性保护参数

4.3 [aggregator] 段——carbon-aggregator（预聚合）

参数默认值含义
LINE_RECEIVER_PORT / PICKLE_RECEIVER_PORT2023 / 2024aggregator 接收端口（镜像默认把它串在 cache 前面）
FORWARD_ALLTrue聚合后的原始点是否也转发下游
DESTINATIONS127.0.0.1:2004聚合结果转发目标（cache）
MAX_AGGREGATION_INTERVALS5缓冲区内允许的聚合窗口数
MAX_QUEUE_SIZE / USE_FLOW_CONTROL10000 / True同 relay

聚合规则本身写在 aggregation-rules.conf，默认该文件为空（无任何预聚合规则生效），典型行如 sys.cpu.load.<server>.avg (60) = average sys.cpu.load.<server>。

五、storage-schemas.conf 保留策略详解（含实测）

5.1 默认内容与语法

默认文件（注释后生效部分）：

[carbon]
pattern = ^carbon\.
retentions = 10s:6h,1m:90d

[default_1min_for_1day]
pattern = .*
retentions = 10s:6h,1m:6d,10m:1800d

语法三要素：

  • [段名]：仅用于展示与校验输出，可读即可；
  • pattern：Python 正则，按文件内出现顺序 first-match-wins 匹配指标路径；
  • retentions：逗号分隔的 精度:时长 列表，如 10s:6h 表示 10 秒一个点、保留 6 小时；支持 s/m/h/d/y 后缀。

💡 技术拓展：多归档精度必须是整数倍递进关系，否则滚动聚合会错位：60s:7d,300s:30d 合法（300/60=5）；180s:7d,300s:30d 非法（300/180=1.67）。validate-storage-schemas.py 会报这类错误。磁盘占用 = Σ(时长/精度) × 每点字节数（固定 12 字节），例如 10s:6h = 2160 点 = 25920 字节。

5.2 实测一：自定义 schema（放对位置才生效）

为 s7custom. 前缀指标自定义「5 秒精度保留 10 分钟 + 1 分钟精度保留 1 天」。关键：自定义段必须插在 pattern 为 .* 的默认段之前。

正确配置（[carbon] 段后、[default_1min_for_1day] 段前插入）：

[s7_custom]
pattern = ^s7custom\.
retentions = 5s:10m,1m:1d

重启后打全新指标并验证归档结构：

echo "s7custom.fixed 3 $(date +%s)" | nc -w 2 127.0.0.1 8129
# 等待约 7 秒刷盘后
whisper-info.py /opt/graphite/storage/whisper/s7custom/fixed.wsp

实测回显（5 秒归档与 1 天最大保留生效）：

aggregationMethod: average
maxRetention: 86400
xFilesFactor: 0.30000001192092896
fileSize: 18760

Archive 0
offset: 40
secondsPerPoint: 5
points: 120
retention: 600

5.3 排障实录：自定义段追加到文件末尾不生效

把同样的 [s7_custom] 段用追加方式写到 storage-schemas.conf 末尾（即默认 .* 段之后），重启并打全新指标 s7custom.fresh，whisper-info.py 实测回显仍是默认 schema（10 秒归档、maxRetention 155520000）：

aggregationMethod: average
maxRetention: 155520000
...
Archive 0
offset: 52
secondsPerPoint: 10
points: 2160
retention: 21600

原因：schema 匹配是文件顺序 first-match-wins，默认段 pattern = .* 兜底所有指标，永远轮不到排在它后面的自定义段。将 [s7_custom] 前移到默认段之前（5.2 配置），同法重测即生效。任何自定义保留策略报障先检查段顺序。

⚠️ 注意：修改 schema 只影响之后新建的 .wsp；同名旧文件不会重建。验证时必须使用全新指标名。

5.4 存量文件迁移

修改保留策略后，存量文件用 resize 迁移：

whisper-resize.py --nobackup /opt/graphite/storage/whisper/old/metric.wsp 5s:10m,1m:1d

批量场景用 whisper-auto-resize.py 按新 schema 目录扫描迁移（详见《Graphite 1.1.10 常用 CLI 命令与工具详解》）。

六、storage-aggregation.conf 聚合规则详解（含实测）

6.1 默认内容

[min]
pattern = \.lower$
xFilesFactor = 0.1
aggregationMethod = min
[max]
pattern = \.upper(_\d+)?$
xFilesFactor = 0.1
aggregationMethod = max
[sum]
pattern = \.sum$
xFilesFactor = 0
aggregationMethod = sum
[count]
pattern = \.count$
xFilesFactor = 0
aggregationMethod = sum
[count_legacy]
pattern = ^stats_counts.*
xFilesFactor = 0
aggregationMethod = sum
[default_average]
pattern = .*
xFilesFactor = 0.3
aggregationMethod = average

三项含义：

  • aggregationMethod：高精度点滚动到低精度归档时的聚合函数（average/sum/min/max/last/avg_zero/absmax/absmin）；
  • xFilesFactor：聚合窗口内非空点比例低于该阈值时结果写 None（0.3 即窗口内 30% 有数才产出聚合点）；
  • 计数器类指标（.sum/.count 与 stats_counts.*）用 sum 且 xFilesFactor=0（一个点也算），仪表类用 average。

6.2 实测：自定义聚合方法

为 s7custom. 指标配置 sum 聚合（同样必须放在 .* 默认段之前）：

[s7_sum]
pattern = ^s7custom\.
xFilesFactor = 0.0
aggregationMethod = sum

重启后打全新指标 s7custom.aggtest，实测回显：

aggregationMethod: sum
maxRetention: 86400
xFilesFactor: 0.0

聚合方法已写入新文件头（对已存在文件可用 whisper-set-aggregation-method.py 在线修改）。

七、graphite-web 与 local_settings.py 详解

7.1 配置文件位置

graphite-web 的 Django 配置在 /opt/graphite/webapp/graphite/local_settings.py，覆盖 settings.py 默认值。一体化镜像中该文件由 entrypoint 依据环境变量模板生成，逐项读取 GRAPHITE_* 环境变量（因此镜像部署下优先用环境变量调整，原生 pip 部署则直接编辑文件）。

7.2 核心参数分类（含环境变量与默认值，实测自镜像生成的 local_settings.py）

访问与展示：

环境变量默认值说明
GRAPHITE_ALLOWED_HOSTS*Django ALLOWED_HOSTS（生产建议收敛为实际域名）
GRAPHITE_TIME_ZONEEtc/UTC展示时区（本部署实测设为 Asia/Shanghai）
GRAPHITE_DATE_FORMAT%m/%图表日期格式
GRAPHITE_UTF8_METRICSfalseUTF-8 指标名支持（有性能代价）
GRAPHITE_DEBUGfalse异常页调试信息（生产禁开）
GRAPHITE_SECRET_KEY随机Django SECRET_KEY（多实例部署需固定同一值）

缓存与集群：

环境变量默认值说明
GRAPHITE_DEFAULT_CACHE_DURATION60render 结果缓存秒数
MEMCACHE_HOST未设设为 host:port 后启用 Memcached 查询缓存（多实例共享）
GRAPHITE_CLUSTER_SERVERS空集群节点列表（逗号分隔），fan-out 查询
GRAPHITE_USE_WORKER_POOLtrue远端查询线程池
GRAPHITE_REMOTE_FIND_TIMEOUT / REMOTE_FETCH_TIMEOUT30 / 60远端 find/fetch 超时（秒）
GRAPHITE_REMOTE_RETRY_DELAY / MAX_FETCH_RETRIES0 / 2重试间隔与次数
FIND_CACHE_DURATION1指标 find 结果缓存秒数

carbonlink（缓存补取）：

环境变量默认值说明
GRAPHITE_CARBONLINK_HOSTS127.0.0.1:7002carbon-cache 的 7002 缓存查询地址，多实例逗号分隔
GRAPHITE_CARBONLINK_TIMEOUT1.0查询超时（秒）
GRAPHITE_CARBONLINK_HASHING_TYPEcarbon_ch多 cache 哈希算法（carbon_ch/crc32）

TagDB：

环境变量默认值说明
GRAPHITE_TAGDBgraphite.tags.localdatabase.LocalDatabaseTagDB本地 SQLite TagDB
REDIS_TAGDBfalse置 1 切换内置 Redis TagDB（graphite.tags.redis.RedisTagDB）
GRAPHITE_TAGDB_CACHE_DURATION60seriesByTag 结果缓存秒数
GRAPHITE_TAGDB_AUTOCOMPLETE_LIMIT100自动补全条数上限

gunicorn 进程模型（镜像扩展）：GRAPHITE_WSGI_PROCESSES（默认 4）、GRAPHITE_WSGI_THREADS（1）、GRAPHITE_WSGI_REQUEST_TIMEOUT（65 秒）、GRAPHITE_WSGI_MAX_REQUESTS（1000）。

日志：GRAPHITE_LOG_FILE_INFO/EXCEPTION/CACHE/RENDERING（默认 info.log/exception.log/cache.log/rendering.log，置于 /var/log/graphite/）；设为 - 输出到 stdout/stderr 适配集中日志。

7.3 附属配置文件

  • graphTemplates.conf：渲染主题与默认样式（默认黑底白字、12 色线条循环 blue,green,red,...、fontName Sans、fontSize 10）；
  • dashboard.conf：自带仪表盘 UI 的默认尺寸（default_graph_width/height = 400/250）；
  • whitelist.conf / blacklist.conf：指标白/黑名单正则（carbon.conf 中 USE_WHITELIST=True 才启用白名单；默认 whitelist 为 .* 全放行，blacklist 默认全注释）；
  • relay-rules.conf：RELAY_METHOD=rules 时的路由表，默认仅 [default] default = true destinations = 127.0.0.1:2004；

八、生产配置模板（实测可用）

适用场景：8GB 内存、SSD 磁盘、单机承载 ≤ 50 万活跃指标、以 statsd 应用埋点为主。一体化镜像环境变量形态：

environment:
  - GRAPHITE_TIME_ZONE=Asia/Shanghai
  - GRAPHITE_ALLOWED_HOSTS=graphite.example.com
  - GRAPHITE_WSGI_PROCESSES=4
  - GRAPHITE_WSGI_THREADS=2
  - GRAPHITE_DEFAULT_CACHE_DURATION=120
  - GRAPHITE_CARBONLINK_HOSTS=127.0.0.1:7002
  - GRAPHITE_TAGDB=graphite.tags.localdatabase.LocalDatabaseTagDB

carbon.conf 关键调整（[cache] 段）：

[cache]
MAX_CACHE_SIZE = 1000000
MAX_UPDATES_PER_SECOND = 1000
MAX_CREATES_PER_MINUTE = 200
CACHE_WRITE_STRATEGY = sorted
WHISPER_FALLOCATE_CREATE = True
CARBON_METRIC_INTERVAL = 10

storage-schemas.conf 关键调整（插入默认段之前，业务分级保留）：

[high_res_7d]
pattern = ^critical\.
retentions = 5s:1h,1m:7d

[app_stats_1y]
pattern = ^stats\.
retentions = 10s:6h,1m:6d,10m:180d,1h:5y

[default_1min_for_1day]
pattern = .*
retentions = 10s:6h,1m:6d,10m:1800d

💡 说明：[high_res_7d] 服务关键指标（5 秒精度只保 1 小时，控制磁盘）；[app_stats_1y] 承接 statsd 产物（stats.* 本身已是 10 秒 flush 聚合值，10s 归档避免精度损失）。各段 precision 均为整数倍递进，validate-storage-schemas.py 校验通过。

九、常见问题

Q1：改了 storage-schemas.conf 但新指标仍是旧归档？ 三个检查点：① 自定义段是否排在 .* 默认段之前（本文 5.3 排障实录的顺序陷阱）；② 验证用的指标名是否为全新（旧 .wsp 不会重建）；③ 是否已重启 carbon-cache（docker compose restart graphite）。

Q2：修改配置必须重启吗？会不会丢数据？ carbon.conf 的多数参数需重启守护进程生效；storage-schemas/aggregation 官方标注每 60 秒扫描变更（对新建文件生效），但对一体化镜像而言重启 carbon 进程更可靠。数据在宿主 bind mount（whisper/），重启不丢指标数据。

Q3：MAX_CREATES_PER_MINUTE 报错 creates limited？ 新指标创建速率超过限流，超限点被丢弃。新服务集中上线时临时调大该值（如 200），稳定后回落；长期洪峰说明指标命名规划不合理（如把 ID 拼进指标名）。

Q4：如何校验配置文件写对了？ validate-storage-schemas.py /opt/graphite/conf/storage-schemas.conf 输出逐段 OK 与 is valid 结论；aggregation-rules/relay-rules 修改后同样重启对应守护进程并观察其日志。

Q5：Web 查询返回 500 或空白？ 查 /var/log/graphite/exception.log（镜像内路径）。常见原因：local_settings.py 语法错误（PYTHONPATH/Django 加载失败）、CLUSTER_SERVERS 指向不可达节点。环境变量形态配置则检查 docker compose logs graphite 中 gunicorn 启动报错。

十、参考链接