使用统计收集

LMCache 默认收集匿名使用数据，以帮助工程团队了解实际工作负载，优先优化并提高可靠性。所有收集的数据都是汇总的，并不包含敏感用户信息。

聚合数据的一个经过清洗的子集可能会公开发布，以惠及社区（例如，查看每日使用报告 here）。

收集了哪些数据？

使用统计信息在 lmcache/usage_telemetry/ 包中实现。启动时发送的一次性消息取决于 LMCache 的运行方式。

当 LMCache **在服务引擎内部**（vLLM、SGLang 和 TensorRT-LLM 的单进程集成）运行时，引擎启动会发送：

• EnvMessage 捕获环境细节，例如云提供商、CPU 信息、总内存、架构、GPU 数量/类型和执行源。

• EngineMessage 记录引擎配置和元数据，包括缓存设置（块大小、本地设备、缓存限制）、远程后端参数、混合设置、模型名称、全局大小，以及 KV Cache 的数据类型/形状。

• MetadataMessage 报告执行元数据：运行开始的时间戳和总持续时间（以秒为单位）。

当 LMCache 作为 独立的多进程 (MP) 缓存服务器 (lmcache server) 运行时，服务器启动会发送：

• EnvMessage 与上述相同的环境快照，取自缓存服务器主机。

• MPServerMessage 记录服务器配置：LMCache 版本、块大小、哈希算法、引擎类型、传输模式、工作池大小、是否启用 P2P、L1 大小和介质（DRAM / GDS / DRAM+DevDAX）、逐出策略、配置的 L2 适配器和序列化类型，以及 L2 存储/预取策略。

  MP 服务器的 --instance-id 永远 不会被发送：它可以由操作员选择，因此可能具有识别性。模型名称在服务器启动时是未知的（vLLM 实例稍后注册），并且不属于此消息的一部分。

In addition to the one-shot messages above, both deployment modes periodically send interval counters (ContinuousContextMessage: tokens retrieved, tokens stored, stored KV bytes, process uptime). Idle intervals are still sent and double as a liveness heartbeat. Single-process mode additionally sends a cache-lifespan histogram (CacheLifespanMessage). The flush interval is LMCACHE_USAGE_TRACK_INTERVAL seconds (default 600).

每个有效负载都携带四个公共字段：

• session_id -- 每个进程生成一次的随机 UUID，将一次性上下文与同一运行的连续消息连接起来。

• machine_id -- 一个随机的 UUID，持久化在 ~/.config/lmcache/machine_id，用于将来自同一台机器的会话分组。它从不派生自硬件标识符（MAC 地址、主机名）。

• schema_version -- 消息模式的版本。

• deployment_mode -- ``single_process``（服务引擎内部的 LMCache）或 ``mp_server``（独立的 MP 缓存服务器）。

这些消息被序列化为 JSON 并通过 POST 发送到 LMCache 使用服务器。

示例 JSON 有效负载

{
  "message_type": "EnvMessage",
  "provider": "GCP",
  "num_cpu": 24,
  "cpu_type": "Intel(R) Xeon(R) CPU @ 2.20GHz",
  "cpu_family_model_stepping": "6,85,7",
  "total_memory": 101261135872,
  "architecture": ["64bit", "ELF"],
  "platforms": "Linux-5.10.0-28-cloud-amd64-x86_64-with-glibc2.31",
  "gpu_count": 2,
  "gpu_type": "NVIDIA L4",
  "gpu_memory_per_device": 23580639232,
  "source": "DOCKER"
}

预览收集的数据

如果您启用 本地日志记录，使用消息将附加到您指定的日志文件中。要检查最近的条目：

tail ~/.config/lmcache/usage.log

配置与选择退出

默认情况下，使用情况跟踪是 启用 的。以下任一选择退出将禁用所有使用情况统计收集：

# LMCache-specific opt-out
export LMCACHE_TRACK_USAGE=false

# The cross-tool "do not track" convention (1/true/yes)
export DO_NOT_TRACK=1

当跟踪被禁用时，InitializeUsageContext 将返回 None，并且不会发送或记录任何数据，也不会创建任何状态文件（例如 machine_id）。

参考

环境变量 / 文件	默认	效果
LMCACHE_TRACK_USAGE	未设置	设置为 false 以禁用所有使用统计数据收集。
DO_NOT_TRACK	未设置	设置为 1/true/yes 以禁用收集（跨工具约定）。
LMCACHE_USAGE_TRACK_URL	http://stats.lmcache.ai:8080	覆盖统计服务器端点（例如，用于私有接收端）。
LMCACHE_USAGE_TRACK_INTERVAL	600	连续消息刷新之间的秒数。
~/.config/lmcache/machine_id	首次发送时创建	保存随机的匿名机器 UUID。删除它以旋转标识符。

本地日志记录

如果您希望在将数据发送到服务器的同时（或替代）记录到文件中，请在初始化时传递一个本地日志路径：

from lmcache.usage_telemetry import InitializeUsageContext

usage_ctx = InitializeUsageContext(
    config=engine_config,
    metadata=engine_metadata,
    local_log="~/.config/lmcache/usage.log"
)

省略 local_log 参数（或传递 None）将禁用本地文件日志记录。