LMCache 多进程模式连续使用遥测设计从 EventBus 指标到 InfluxDB/Grafana 舰队面板【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache本篇技术指南基于 docs/design/usage_telemetry/continuous_metrics.md 展开系统讲解 LMCache 在多进程MP缓存服务器模式下如何持续采集部署长什么样、缓存做了多少事的匿名使用指标并将其落入 InfluxDB、最终呈现在 Grafana 舰队面板上。文章覆盖 map-reduce 式MetricSpec指标管线、ContinuousContextMessage线格式、InfluxDB 的 tag/field 分桶规则、混合注意力架构full / fullSWA / fulllinear / DSA归因方案与 Chunk 复用追踪器读完你可以理解 MP 连续遥测的完整数据通路并掌握新增一条指标/消息类型的方法与约束。1. 背景这条文档在 LMCache 遥测体系中的位置LMCache 的匿名使用遥测usage telemetry整体位于 lmcache/usage_telemetry/其作用是回报 LMCache 部署形态与缓存收益面向的消费者是LMCache 维护者接收端为 InfluxDB → Grafana。它不是运维可观测性——面向部署运维者的 Prometheus/OTel 指标分别位于 lmcache/v1/mp_observability/MP 模式与 lmcache/observability.py单进程模式。两套系统共享部分事件源但消费者、传输通道与退出开关彼此独立。在遥测包内部本设计文档处于连续指标这条支线上docs/design/usage_telemetry/README.md整个遥测包的总契约消息 schema、身份、退出、故障隔离、扩展指南本文档continuous_metrics.mdMP 模式连续指标mp-continuous-countersPR #4098 已随版本发布的目标、架构、InfluxDB schema 规则与后续路线图docs/design/usage_telemetry/l2_metrics.md同一条支线上的兄弟设计覆盖 MP 缓存服务器的 L2 存储层connector 归因、前缀命中率、占用率。需要说明的是本文档属于设计/路线图性质其中mp-continuous-counters对等计数已经落地而model-arch-attribution、chunk-tracker-*、connector-model-type等仍处于规划阶段文中会明确区分已实现与规划中。2. 目标为什么要做 MP 连续遥测单进程模式下LMCache 已经有基于LMCacheStatsLogger的连续计数见 README.md 的 Reporting paths 一节但 MP 缓存服务器作为一个独立常驻进程此前只有启动时的一次性快照EnvMessage、MPServerMessage运行时做了什么完全不可见。本设计确立了四个目标对等性ParityMP 模式也要能产出与单进程相同的连续指标ContinuousContextMessage这一项已实现舰队级面板Fleet dashboards例如每周 KV 总吞吐量命中率随时间变化这类跨部署聚合混合模型归因Hybrid-model attribution按注意力架构区分 KV 吞吐量——full全注意力、fullSWA滑动窗口、fulllinear线性注意力、DSADeepSeek Sparse Attention 类稀疏架构复用洞察Reuse insights理想化无限存储命中率、chunk 生命周期时长、复用模式短突发 vs 长持续。从代码结构看这些目标决定了两条实现主线对等计数已实现MetricSpec管线的默认注册表与复用追踪规划中ChunkReuseTracker纯类 订阅接线。3. 架构map-reduce 的MetricSpec指标管线3.1 核心思想MP 连续遥测将每条指标定义为一个map-reduce 式MetricSpec契约与默认注册表都集中在 lmcache/usage_telemetry/metric_specs.pymapextract把 EventBus 上的一个事件映射为一个数值样本返回None表示跳过该事件reduce把一个 flush 间隔内缓冲的所有样本折叠成一个字段值sum是最常见的选择event_type指标采样自哪个 EventBus 事件field归约结果写入ContinuousContextMessage的哪个字段。# lmcache/usage_telemetry/metric_specs.py节选 dataclass(frozenTrue) class MetricSpec: event_type: EventType field: str extract: Callable[[Event], int | float | None] reduce: Callable[[Sequence[int | float]], int | float]3.2 已实现的默认注册表对等计数default_metric_specs(chunk_size)目前注册三条指标均来自仅由 lmcache 驱动的传输路径发布的事件MP_RETRIEVE_END/MP_STORE_END事件类型定义见 lmcache/v1/mp_observability/event.py指标字段事件源extractmapreduceinterval_num_hit_tokensMP_RETRIEVE_ENDretrieved_count×chunk_sizesuminterval_num_stored_tokensMP_STORE_ENDstored_count×chunk_sizesuminterval_stored_kv_sizeMP_STORE_ENDtotal_bytes精确字节数sum值得注意的是chunk_size参数事件元数据携带的是chunk 计数需要乘以服务器 chunk 大小token 数才能换算成 token 级指标。三个字段与ContinuousContextMessagelmcache/usage_telemetry/messages.py的指标字段一一对应——这是硬性契约MPContinuousUsageReporter.__init__会做 exact-cover 校验spec 字段集合必须与消息字段排除sequence_number、uptime_seconds这两个 reporter 自填字段精确相等否则直接抛ValueError。3.3 双线程模型drain 线程缓冲flush 线程归约发送执行模型由 lmcache/usage_telemetry/mp_continuous.py 中的MPContinuousUsageReporter一个EventSubscriber实现drain 线程回调按get_subscriptions()的映射订阅事件。回调只做两件事——extract取样本、追加到按字段分组的缓冲字典当某个缓冲长度达到max_buffered_samples默认 65536时调用wake()提前唤醒flush 线程防止两轮 flush 之间内存无界增长。flush 线程归约发送由 lmcache/usage_telemetry/flush.py 的start_usage_flush_thread创建ThreadLevel.LOW的PeriodicThread注册进全局PeriodicThreadRegistry线程名须进程内唯一。每隔LMCACHE_USAGE_TRACK_INTERVAL秒默认600 秒见usage_flush_interval_seconds()非法值回退默认、下限钳制为 1 秒执行一次flush()加锁换取缓冲快照、归约出各字段、组装ContinuousContextMessage含递增sequence_number与uptime_seconds、经build_usage_payload加盖身份与 schema 后 POST 到cache-usage端点。空间隔 心跳即使一个间隔内没有任何事件也要照常发送一条零值消息充当会话心跳发送失败则丢弃该间隔数据而非重试遥测绝不能累积无界状态后端通过sequence_number的跳号识别丢失的间隔而非空闲的间隔。EventBus.stop()时会触发一次最终 flush把最后一个不完整间隔的数据补发出去。入口函数InitializeMPContinuousUsage(event_bus, chunk_size, sender)由run_cache_server启动路径调用遥测被禁用或初始化失败时返回None且全程永不抛异常详见下文故障隔离。4. 消息 schemamessages.py是唯一的真源MP 连续消息复用共享消息类型ContinuousContextMessage被单进程与 MP 两种模式共同使用靠 payload 上统一加盖的deployment_modesingle_process/mp_server见 messages.py 的DeploymentMode枚举区分来源。MP 特有的增量一律是新消息类型而不是往共享类上添字段MP 与非 MP 的代码/端点拆分/mp/前缀被刻意推迟为单独的未来 PR。schema 契约要点与 README.md 一致类名即线格式message_typebuild_usage_payload从类名派生发送方无法与 schema 产生分歧每条消息以类属性声明ENDPOINTContinuousContextMessage为cache-usage字段必须扁平且可 JSON 序列化列表会按定界符拼接成字符串因为后端按扁平 key-value 存储session_id、machine_id、schema_version、deployment_mode由build_usage_payload统一加盖不在消息类中声明USAGE_SCHEMA_VERSION 1仅当已有字段语义改变时才递增新增消息类型或字段不算 schema bump。5. InfluxDB schema 规则舰队级聚合的前提MP 连续遥测的接收端是 InfluxDB本设计为其规定了五条硬规则这些规则直接决定了后续 Grafana 面板的写法Tag 只用低基数字段deployment_mode、message_type、model_name、attn_arch、lmcache_version作为 tagsession_id永远是 field 而非 tag——它是每会话一个的高基数值作为 tag 会导致 InfluxDB 序列数无界膨胀。发间隔增量不发累计计数例如每周 KV 总量用SUM(...) GROUP BY time(1w)计算即可且重启安全累计计数在进程重启后归零会破坏聚合。直方图以字典字段发送后端 ingest 时将桶展开为lebound标签的点正好对应 Grafana heatmap 格式。发送分子/分母/采样率绝不发送预先算好的比值命中率这类比率必须由后端从原始计数推导否则无法跨部署聚合或加权。sequence_number跳号 丢失间隔这是后端判断数据缺口而非空闲的唯一信号。6. 混合注意力架构归因model-arch-attribution规划中为了回答不同注意力架构的 KV 吞吐量各占多少本设计规划从KV-cache 注册时刻的AttnWindowDesc推导attn_archnum_chunks_in_sw全为-1→full纯全注意力窗口宽度 1个 chunk →fullswa含滑动窗口注意力 1→fulllinear线性注意力use_mla作为独立的一比特维度Multi-head Latent Attention 单独标记。attn_arch通过重新落地的MPInstanceMessage注册时的实例消息发送并作为 tag 打在按模型聚合的计数器上例如GROUP BY model_name, attn_arch的 KV 吞吐面板。文档明确标注了一个已知缺口DSA 类架构在 KV 布局上是不可见的其稀疏模式不体现在窗口描述里需要连接器connector在注册时额外透传 Hugging Face 的model_type才能精确归因——这正是connector-model-typePR 的动机。这条属于规划中内容实现状态以仓库为准。7. Chunk 复用追踪器chunk-tracker-core/chunk-tracker-wiring规划中本设计用三个洞察需求收尾复用分析全部由规划中的ChunkReuseTracker承载采样与表结构采用确定性哈希采样hash % R 0R 64将样本量限制在有界表中每条被采样 chunk 记录first_seen、first_reuse、last_access、reuse_count、was_stored。哈希永远不离开进程线上只发送分桶聚合值——这是隐私底线。数据源是MP_LOOKUP事件事件定义见 lmcache/v1/mp_observability/event.py其事件发布已按订阅者门控chunk_hashes元数据已就绪见 lmcache/v1/mp_observability/event_bus.py。Env 旋钮采样分母R、空闲 TTL、表容量上限。理想命中率Ideal hit rate采样访问中此前见过的比例。它与实际命中率之差 容量/策略不足造成的可提升空间headroom。注意其视界受限于追踪器保留期进程重启会重置。生命周期Lifespanlast_access − first_reuse在 chunk 退役时发出空闲超过 TTL ≈ 3 天判定退役对数分桶到约 1 个月。因容量上限被强制退役的情况单独计数与空闲退役区分开。复用模式Reuse pattern退役时输出reuse_count × lifespan的二维直方图用于区分多轮突发 / 日度持续 / 共享前缀三类模式外加一维的 reuse 间隔直方图。与旧方案的替代关系单进程模式原有的 lifespan 直方图store→reuse 间隔桶上限约 3.5 天不再移植到 MP 模式——chunk 追踪器是它的上位替代。8. 故障隔离、隐私与退出连续遥测必须无感连续遥测运行在缓存服务器的常驻路径上任何失败都不得影响缓存/服务主流程详见 README.md 的 Failure isolation 一节MP 事件回调与 reporter 的flush均以guard.swallow_telemetry_errors装饰lmcache/usage_telemetry/guard.py异常只记 debug 日志并吞掉UsageMessageSender.send额外吞掉全部传输错误并设 5 秒超时发送失败丢数据不重试不累积状态以sequence_number跳号标记契约测试位于 tests/test_usage_telemetry.pyTestFailureIsolation注入一个必抛异常的 transport启动上报与 flush 都不得崩测试通过注入 recording stub 完成任何测试都不允许碰网络且 tests/conftest.py 有 autouse fixture 全局禁用遥测防止测试过程误上报。隐私规则标识符为随机 UUID绝不从硬件派生无 MAC、主机名、/etc/machine-idMP 服务器的instance_id运维可设置的--instance-id可能含标识性字符串刻意排除在 payload 之外只留在运维侧 OTel 的service.instance.id不上送任何 prompt、key 或 KV 内容模型名会上报因为它标识的是公开模型架构而非具体部署。退出语义唯一开关是is_usage_tracking_enabled()lmcache/usage_telemetry/identity.py两个条件任一满足即关闭LMCACHE_TRACK_USAGEfalse或DO_NOT_TRACK为1/true/yes跨工具惯例。关闭后工厂函数返回None、连续 reporter 直接 no-op且不会创建任何状态文件如~/.config/lmcache/machine_id。9. PR 路线图与开放决策9.1 路线图一览PR内容状态mp-continuous-countersmap-reduce reporter对等计数 uptime_seconds已发布#4098model-arch-attributionL1 逐出计数 MPInstanceMessage重新落地 attn_arch 按模型 tag规划中chunk-tracker-coreChunkReuseTracker纯类 单元测试不接线规划中chunk-tracker-wiring追踪器订阅者 ReusePatternMessage依赖chunk-tracker-core规划中connector-model-type连接器注册时透传 HFmodel_typeDSA、精确架构规划中influx-ingest后端仓库外JSON→Influx 映射 起始 dashboard仓库外并行其中 L1 逐出计数已随mp-continuous-counters半落地事件源L1_KEYS_EVICTED定义见 lmcache/v1/mp_observability/event.pyL2 侧逐出计数被拆分到兄弟文档 docs/design/usage_telemetry/l2_metrics.md 管辖L2_KEYS_EVICTEDevent.py。9.2 开放决策tag/field 划分需与真实 Influx ingest 确认——即第 5 节规则在落地时的最终形态model-arch-attribution的注册信号选型新增MP_KV_REGISTERED事件类型还是直接挂注册表 hook设计倾向是更轻的事件方案。10. 小结如何阅读与验证这份设计一句话概括MP 连续遥测 把 EventBus 事件 map-reduce 成ContinuousContextMessage按 InfluxDB 规则落库供维护者做舰队级缓存洞察。已实现的骨架在 lmcache/usage_telemetry/metric_specs.py指标定义与 lmcache/usage_telemetry/mp_continuous.py执行管线中可直接阅读schema 以 lmcache/usage_telemetry/messages.py 为准行为契约由 tests/test_usage_telemetry.py 守护。规划中的架构归因与复用追踪部分请以仓库后续实现为准本设计文档是理解其动机与数据语义的最佳入口。【免费下载链接】LMCacheLMCache: Supercharge Your LLM with the Fastest KV Cache Layer项目地址: https://gitcode.com/GitHub_Trending/lm/LMCache创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考