可观察性

LMCache MP 模式（多进程）提供三种互补的可观察性模式：指标（通过 OTel 的 Prometheus 计数器）、日志（带有可选 OTel 日志转发的 Python 日志记录）和 追踪（OTel span，用于每个请求的延迟分析）。

这三种模式都由一个内部的 EventBus 提供支持，该总线将生产者（L1Manager、StorageManager、MPCacheServer）与订阅者解耦。

快速开始

默认情况下，指标和日志记录是启用的；追踪是禁用的。无需额外的标志：

lmcache server \
    --l1-size-gb 100 --eviction-policy LRU

服务器然后在其 HTTP 前端端口 (--http-port, 默认 8080) 上暴露 Prometheus 指标于 /metrics：

curl http://localhost:8080/metrics | grep lmcache_mp_

重要

对于 lmcache server，/metrics 位于 --http-port``（默认 ``8080），而不是 --prometheus-port：HTTP 前端已经提供了 /metrics，因此独立的 Prometheus 服务器被禁用，--prometheus-port 在此命令下没有效果。--prometheus-port 是 前端无入口点的指标端点（python -m lmcache.v1.multiprocess.server 和 lmcache trace replay）— 请参见 /metrics 的位置。还要注意，指标是惰性加载的：一个系列只有在第一次存储/检索产生它之后才会出现，因此在抓取之前请先驱动一些流量。

要查看 L2（存储层）指标，请使用 --l2-adapter 附加一个 L2 后端。最简单的后端是本地文件系统：

lmcache server \
    --l1-size-gb 100 --eviction-policy LRU \
    --l2-adapter '{"type": "fs", "base_path": "/data/lmcache/l2"}'

要启用追踪而不是（或与）Prometheus 拉取并行，请提供 OTLP 端点——这将切换指标到 **推送模式**（参见 在 Grafana 中查看指标）：

lmcache server \
    --l1-size-gb 100 --eviction-policy LRU \
    --enable-tracing --otlp-endpoint http://localhost:4317

/metrics 的位置

拉模式的 /metrics 端点根据入口点的不同而服务于两个地方。嵌入 uvicorn HTTP 前端的入口点在此提供该端点（并禁用独立的 Prometheus 服务器）；没有 HTTP 前端的入口点则在 --prometheus-port 上启动独立服务器。

入口点	HTTP 前端？	拉取模式 /metrics 端点
lmcache server	是	--http-port``（默认 ``8080）；--prometheus-port 被忽略
python -m lmcache.v1.multiprocess.server	不	--prometheus-port (默认 9090)
lmcache trace replay	不	--prometheus-port (默认 9090)

在 推送模式 (--otlp-endpoint 设置) 下，这些都不提供 /metrics — 指标被推送到收集器。

在 Grafana 中查看指标

将 LMCache 指标导入 Grafana 有两种方法。根据您是否还想要 跟踪 进行选择。

路径	服务器标志	您运行的内容	提供给你
A. 打包堆栈	--otlp-endpoint (推送)	docker compose up 在 examples/observability/	指标 + 跟踪，Grafana 自动配置的 LMCache 仪表板
B. 拉取模式	无 (默认)	您自己的 Prometheus + Grafana 抓取 :8080	仅限指标，最小的移动部件，无收集器

路径 A — 打包的 Prometheus + Tempo + Grafana

该存储库提供了一个可直接运行的堆栈（OpenTelemetry Collector → Prometheus + Tempo → Grafana），位于 examples/observability/ 下。Grafana 配备了 预配置的 LMCache 仪表板和数据源，并启用了匿名访问，因此无需点击登录。

# 1. Start the observability stack (Collector :4320, Prometheus, Tempo,
#    Grafana :3000)
cd examples/observability
docker compose up -d

# 2. Start the LMCache server (+ vLLM) pushing OTLP to the collector
MODEL=/path/to/model bash start-server.sh

# 3. Generate traffic, then open Grafana
#    http://localhost:3000  ->  Dashboards  ->  "LMCache"

在这个路径中，服务器将数据推送到 Collector，Prometheus 从 Collector 中抓取数据，因此您*不*直接从服务器的 :8080 抓取数据。

路径 B — 拉取模式（仅限指标，无收集器）

如果您只想要指标，可以完全跳过收集器，让 Prometheus 直接抓取服务器的 /metrics 端点。启动服务器时 不 使用 ``--otlp-endpoint``（请参见上面的快速开始），然后：

# 1. Prometheus config: scrape the server's HTTP-frontend port (8080)
cat > prometheus.yml <<'YAML'
global:
  scrape_interval: 5s
scrape_configs:
  - job_name: lmcache
    static_configs:
      - targets: ["localhost:8080"]   # --http-port, NOT --prometheus-port
YAML

# 2. Run Prometheus (:9090) and Grafana (:3000) on the host network so
#    they can reach localhost:8080 and each other.
docker run -d --name lmcache-prom --network host \
    -v "$PWD/prometheus.yml:/etc/prometheus/prometheus.yml:ro" \
    prom/prometheus

docker run -d --name lmcache-grafana --network host \
    -e GF_AUTH_ANONYMOUS_ENABLED=true \
    -e GF_AUTH_ANONYMOUS_ORG_ROLE=Admin \
    grafana/grafana

然后在 Grafana (http://localhost:3000)：

1. 添加数据源 → Prometheus → URL http://localhost:9090 → 保存。

2. 导入仪表板：仪表板 → 新建 → 导入 → 上传 examples/observability/grafana/provisioning/dashboards/lmcache.json 并选择 Prometheus 数据源。这是捆绑堆栈提供的相同仪表板（缓存命中率、L1/L2 缓存操作、L1↔L2 吞吐量、逐出循环、EventBus 健康状况等）。

验证整个管道：

# target should be "up"
curl -s localhost:9090/api/v1/targets | grep -o '"health":"[a-z]*"'

# after driving traffic, L2 store throughput (GB/s) per backend:
curl -s localhost:9090/api/v1/query --data-urlencode \
  'query=sum by (l2_name) (rate(lmcache_mp_l2_store_throughput_GB_per_second_sum[1m]))
         / sum by (l2_name) (rate(lmcache_mp_l2_store_throughput_GB_per_second_count[1m]))'

请参阅 指标 以获取完整的指标目录和更多 PromQL 示例。

备注

--network host``（如上所述）是在 Linux 上最简单的选项。在 Docker Desktop（macOS/Windows）上，去掉 ``--network host，使用 -p 9090:9090 / -p 3000:3000 发布端口，并将抓取目标设置为 host.docker.internal:8080，Grafana 数据源 URL 设置为 http://host.docker.internal:9090。

配置

参数	默认	描述
--disable-observability	关闭	主开关：完全禁用 EventBus（不注册任何指标、日志记录或追踪订阅者）。
--disable-metrics	关闭	跳过指标订阅者（Prometheus 端点未启动）。
--disable-logging	关闭	跳过日志订阅者。
--enable-tracing	关闭	注册追踪订阅者。需要 --otlp-endpoint。
--event-bus-queue-size	10000	事件总线队列中最大事件数，超过后将进行尾部丢弃。
--otlp-endpoint	(无)	OTLP gRPC 端点（例如 http://localhost:4317）。用于导出指标（推送模式）和追踪数据。
--prometheus-port	9090	独立 Prometheus /metrics 服务器的端口。仅由无前端的入口点启动（python -m lmcache.v1.multiprocess.server，lmcache trace replay）。在 lmcache server 中被忽略——在这里，HTTP 前端在 --http-port 上提供 /metrics，因此独立服务器被禁用。请参见 /metrics 的位置。
--http-port	8080	HTTP 前端的端口，用于在拉取模式下（当 --otlp-endpoint 未设置时）为 lmcache server 提供 Prometheus /metrics 端点。
--metrics-sample-rate	0.01	用于生命周期直方图的 chunk/block 采样比例 (0, 1.0]。计数器始终统计所有事件。默认值为 1%。
--enable-extra-logging	关闭	Periodically log per-GPU L0<->L1 store/retrieve throughput and token counts, plus L1 memory usage, at INFO level. Conflicts with --disable-observability. See 日志记录.
--extra-logging-interval	10.0	Seconds between extra-logging emissions. Values below 1.0 are limited by the 1 Hz internal heartbeat.
--trace-level	(无)	在指定级别启用追踪录制。目前仅支持 storage（记录 StorageManager 公共 API 调用以便离线回放）。未设置时，追踪录制关闭。详情请参见 追踪记录。
--trace-output	(无)	追踪文件的写入路径。若设置了 --trace-level 但省略此项，将在 $TMPDIR 下自动生成一个带时间戳的文件（lmcache-trace-<pid>-<UTC>.lct），并以 INFO 级别记录其路径。

环境变量：

变量	默认	描述
LMCACHE_LOG_LEVEL	INFO	控制所有 LMCache 日志记录器的日志级别。有效值：DEBUG、INFO、WARNING、ERROR、CRITICAL。

• 指标
• 日志记录
• 追踪