Graphite 0.9.12 补丁版本解析:Django 1.3 时区兼容与 Carbon 缓存查询回归修复
Graphite 0.9.12 补丁版本解析:Django 1.3 时区兼容与 Carbon 缓存查询回归修复
Graphite 0.9.12 是 0.9.11 发布两天后的补丁版本(2013-08-22),专门修复 0.9.11 引入的两个关键回归:django.utils.timezone 导致 Django 1.3 兼容性被破坏,以及 graphite.util 缺失导入导致 cache-queries(缓存查询)失效。本文以该发布说明为核心,结合仓库源码(webapp 目录)逐条剖析这两个问题的成因、修复方式与涉及的底层实现,并给出升级与安装建议,帮助运行 Graphite 0.9.11 的用户理解为何必须立即升级。
发布背景:为何 0.9.12 如此紧急
按照 docs/releases/0_9_12.rst 的说明,0.9.12 是一个 patch release(补丁发布),其存在意义完全是为了修复 0.9.11 中“漏网”的两个严重回归(critical regressions)。而 0.9.11 自身在 docs/releases/0_9_11.rst 中已经带有明显的警示:
NOTE: Graphite 0.9.11 has a regression which breaks cache queries. Please use 0.9.12 instead
也就是说,0.9.11 在发布当天(2013-08-20)即被确认存在破坏缓存查询的缺陷,0.9.12(2013-08-22)作为其直接替代版本在两天后紧急推出。0.9.11 本体的发布说明也因此长期保留这条"请改用 0.9.12"的提示。对于任何正在评估或已经部署 0.9.11 的运维人员,0.9.12 是必须落地的版本。
两个被修复的回归分别是:
- Usage of django.utils.timezone breaks Django 1.3 compatibility —— 代码直接使用了
django.utils.timezone,而该模块在 Django 1.3 中并不存在(Django 1.4 才引入),导致运行在 Django 1.3 上的 Graphite 在导入相关模块时直接抛错。 - Missing import in graphite.util breaks cache-queries ——
graphite/util.py中缺少必要的导入语句,导致依赖该模块的 cache-queries 功能(即通过 CarbonLink 读取 carbon 内存缓存中尚未落盘的实时数据)运行时失败。
回归一:django.utils.timezone 与 Django 1.3 兼容性
问题本质:Django 1.3 没有 timezone 模块
django.utils.timezone 是 Django 1.4 起引入的时区支持基础设施(包含 now()、make_aware()、get_current_timezone() 等 API)。在 Django 1.3 中导入它必然触发 ImportError。Graphite 0.9.11 之前的代码基中,时区处理主要依赖 pytz 与 datetime 的原始组合,而 0.9.11 引入了 django.utils.timezone 的直接使用,从而将 Django 1.3 用户挡在了门外。
仓库中的实际使用点(修复方向)
从当前仓库代码看,与 django.utils.timezone 相关的直接导入集中在三处:
- webapp/graphite/util.py:
from django.utils.timezone import make_aware,用于epoch()函数,把不带时区信息的datetime转换为带时区对象再换算成 epoch 秒; - webapp/graphite/events/views.py:
from django.utils.timezone import now,在 events 模块的post_event()中作为默认时间戳(webapp/graphite/events/views.py); - webapp/tests/test_events.py 与 webapp/tests/test_attime.py 等测试代码中同样引用了
django.utils.timezone。
其中 webapp/graphite/util.py 是全局工具模块,几乎被渲染、存储、CarbonLink 等所有核心路径间接依赖。一旦该模块在 Django 1.3 下导入失败,波及面是整个 Web 应用,而不仅仅是 events 功能。
值得注意的是,当前仓库的 settings.py 已经显式开启 Django 的时区支持:USE_TZ = True(webapp/graphite/settings.py),并将默认时区设为 UTC(webapp/graphite/settings.py)。这代表后续版本已经完整走 Django 时区体系,而 0.9.12 的修复属于在 0.9.11 与完整时区化之间的过渡:在不破坏 Django 1.3 的前提下继续提供正确的时间换算。相关测试(如 webapp/tests/test_util.py 中对 epoch() 的时区感知测试)也印证了时区处理在 graphite-web 中属于被持续验证的核心逻辑。
对运维的启示:版本依赖对齐
0.9.11 发布说明明确要求 Django >= 1.3(见 docs/releases/0_9_11.rst)。0.9.12 的修复正是为了兑现这一承诺。在升级 0.9.12 时:
- 确认运行环境满足
Django >= 1.3(0.9.12 的时区修复正是为兼容 1.3 而设计); - 若仍使用 Django 1.3,升级后应重点回归验证时间相关行为(
from/until参数解析、events 时间戳、图形 x 轴刻度),可参考 webapp/tests/test_attime.py 中的时区与 DST 用例; - 若已运行更高版本 Django,同样建议升级,以同时获得第二个回归(cache-queries)的修复。
回归二:graphite.util 缺失导入与 cache-queries
cache-queries 是什么
cache-queries(缓存查询)是 Graphite 数据通路中的关键一环:carbon-cache 会把最新到达、尚未轮转写入 whisper 文件的指标点保存在内存缓存中,graphite-web 通过 CarbonLink 协议向 carbon 发起 cache-query 请求,把这段"最新鲜"的数据与磁盘 whisper 数据合并后一起渲染。没有 cache-queries,图表末尾的最新数据点会缺失,实时性大打折扣。
这条链路的完整实现位于 webapp/graphite/carbonlink.py:
def query(self, metric):
request = dict(type='cache-query', metric=metric)
results = self.send_request(request)
log.cache("CarbonLink cache-query request for %s returned %d datapoints" % (
metric, len(results['datapoints'])))
return results['datapoints']
send_request() 将请求以 pickle 序列化(协议版本由 CARBONLINK_PICKLE_PROTOCOL 控制),前附 4 字节大端长度前缀后经 socket 发送(webapp/graphite/carbonlink.py),响应同样按"长度前缀 + pickle 体"接收反序列化(webapp/graphite/carbonlink.py)。
合并逻辑:为什么"缺失导入"会导致功能断裂
cache 查询结果并不是直接返回给前端,而是要与 whisper 磁盘数据合并。当前仓库中该合并逻辑位于 webapp/graphite/readers/utils.py 的 merge_with_carbonlink():
def merge_with_carbonlink(metric, start, step, values, aggregation_method=None, raw_step=None):
"""Get points from carbonlink and merge them with existing values."""
cached_datapoints = []
try:
cached_datapoints = CarbonLink().query(metric)
except BaseException:
log.exception("Failed CarbonLink query '%s'" % metric)
cached_datapoints = []
if isinstance(cached_datapoints, dict):
cached_datapoints = list(cached_datapoints.items())
return merge_with_cache(
cached_datapoints, start, step, values,
func=aggregation_method, raw_step=raw_step)
whisper 读取器在完成磁盘读取后调用该函数(webapp/graphite/readers/whisper.py),merge_with_cache() 依据聚合方法(sum/average/max/min/last/avg_zero)把缓存点按目标 step 归并进时间序列(webapp/graphite/readers/utils.py)。该合并逻辑在 webapp/tests/test_readers_util.py 中有专门的单测覆盖(如 MergeWithCacheTests 中 step 不一致、聚合函数等场景)。
回到 0.9.12 的回归:graphite.util 是 carbonlink.py(通过 from graphite.util import load_module, unpickle, parseHosts,见 webapp/graphite/carbonlink.py)以及 readers/utils.py(通过 graphite.readers.utils 间接依赖)的底层依赖。0.9.11 在 graphite/util.py 中漏写了一个导入,导致整个模块链在导入阶段抛出 NameError/ImportError,CarbonLink().query(metric) 在模块加载时就已经失败,cache-queries 全线不可用。0.9.12 补上该导入后链路恢复。
完整的缓存体系:请求缓存与数据缓存的区分
要理解 cache-queries 在整体中的位置,还需要看到 graphite-web 在 render 路径上的两级缓存(webapp/graphite/render/views.py):
- 请求缓存(request cache):用
hashRequest()对整个请求参数归一化后取 MD5 作为 key(webapp/graphite/render/hashing.py),命中则直接返回已渲染的完整响应; - 数据缓存(data cache):用
hashData()对 targets + 时间窗 + xFilesFactor 取 key(webapp/graphite/render/hashing.py),命中则跳过evaluateTarget()的数据拉取,仅重做渲染。
cache-queries 属于"数据拉取"阶段的实时数据补充,与上述两级"结果缓存"不同:前者从 carbon 内存取最新点,后者复用已算好的结果。二者配合,才构成 Graphite 的"近实时 + 高吞吐"渲染模型。在 renderView 中,用户还可通过 noCache 参数绕过两级缓存,用 cacheTimeout 控制缓存时长(webapp/graphite/render/views.py),相关行为在 webapp/tests/test_render.py(如 noCache、cacheTimeout=0 用例)中有测试覆盖。
CarbonLink 配置参考
cache-queries 依赖 CarbonLink 与 carbon-cache 的连通性,相关配置默认值位于 webapp/graphite/settings.py,可在 webapp/graphite/local_settings.py.example 中覆盖:
| 配置项 | 默认值 | 说明 |
|---|---|---|
CARBONLINK_HOSTS |
["127.0.0.1:7002"] |
carbon 实例列表,格式为 server:port:instance |
CARBONLINK_TIMEOUT |
1.0 |
单次请求超时(秒) |
CARBONLINK_RETRY_DELAY |
15 |
某主机失败后进入黑名单的秒数 |
CARBONLINK_PICKLE_PROTOCOL |
-1 |
pickle 协议版本,-1 表示最高版本 |
CARBONLINK_HASHING_TYPE |
'carbon_ch' |
一致性哈希类型,可选 carbon_ch/fnv1a_ch/mmh3_ch |
CARBONLINK_HASHING_KEYFUNC |
None |
自定义哈希 key 函数,格式 模块路径:函数名 |
CARBON_METRIC_PREFIX |
'carbon' |
匹配该前缀的指标会广播到所有 carbon 主机 |
REPLICATION_FACTOR |
1 |
副本因子,不能超过主机数 |
主机字符串由 parseHosts() 解析(webapp/graphite/util.py),支持 server:port 与 IPv6 的 <a href="https://link.gitcode.com/i/7ad982334e2f1334e29a64820a8d240e" target="_blank">addr]:port 写法,也可带 :instance 后缀用于区分同一主机上的多个 carbon 实例。多实例部署下,CarbonLinkPool 通过 ConsistentHashRing 按指标键选择主机([webapp/graphite/carbonlink.py),并维护每主机连接池与失败黑名单。
升级 0.9.12 后,若 cache-queries 依然不生效,可优先检查以上配置与 carbon 7002 端口连通性;日志中 log.cache("CarbonLink cache-query request ...") 的条目(webapp/graphite/carbonlink.py)可用于确认请求确实发出并返回了数据点。
安装与升级指引
0.9.12 发布说明给出的安装途径与 0.9.11 一致,分为源码包与 PyPI 两种:
- 源码包:graphite-web、carbon、whisper 三个项目各提供 0.9.12 的源码归档(GitHub releases 目录);
- PyPI:
graphite-web、carbon、whisper三个包均可通过pip安装。
按照 0.9.11 发布说明中给出的升级经验(docs/releases/0_9_11.rst):
- 建议将 graphite-web、carbon、whisper 三个包一起升级到 0.9.12,以获得一致的版本组合;
- 其中 carbon 与 whisper 因改动相互耦合,必须同时升级;graphite-web 可单独升级;
- 升级前先确认 Django >= 1.3 依赖已满足;
- 与往常一样,建议将现有的
local_settings.py等配置文件与示例配置(如 webapp/graphite/local_settings.py.example、conf/dashboard.conf.example)逐一比对,及时了解新特性与新增配置项。
总结:0.9.12 的定位与升级价值
0.9.12 是一个"小而必要"的补丁版本:
- 对 Django 1.3 用户,它恢复了安装与启动兼容性;
- 对 所有用户,它恢复了 cache-queries 实时数据链路,避免图表末尾缺失最新数据点;
- 它是 0.9.11 的官方替代版本——0.9.11 的发布说明至今保留着"请改用 0.9.12"的显著提示。
从源码层面看,这两个修复分别落在时区工具模块(graphite/util.py 的 epoch() 时区换算)与 CarbonLink 导入链(graphite/util.py → graphite/carbonlink.py → readers/utils.py 的 merge_with_carbonlink())之上,而这两条链路恰好是 Graphite 时间正确性与数据实时性的基石。因此,0.9.12 的升级价值不亚于一次完整的 minor release,任何运行 0.9.11 的部署都应立即跟进。