Core deployment pattern
Use a Loki-compatible read proxy in front of VictoriaLogs
Loki-VL-proxy sits between Grafana or other Loki clients and VictoriaLogs. It keeps the read-side Loki API shape, translates metadata and query behavior where needed, and exposes route-aware telemetry so the middle layer stays operable.
What the proxy actually does
- Accepts Loki-compatible read and metadata requests.
- Translates query and metadata paths toward VictoriaLogs and optional rules backends.
- Shapes responses into the tuple and field contracts Grafana expects.
- Adds a 4-tier cache stack (Tier0, L1 memory, L2 bbolt disk, L3 peer) plus request coalescing and a sliding-window circuit breaker (30s window, 5 failure threshold) to protect the backend.
- Prefilters long-range queries and eliminates ~81.6% of empty-window backend calls.
What it intentionally does not do
- It does not become a generic log ingestion system.
- It does not ask Grafana to switch to a custom datasource plugin.
- It does not hide its own latency or cache behavior from operators.
- It does not open write ownership for Loki push paths.
Measured throughput vs Loki baseline (30s bench, Apple M5 Pro)
All figures are multiples of the Loki baseline at the same workload. “Warm” means L1 cache was populated; “cold” means a fresh process with no prior cache state.
| Workload | Proxy warm | Proxy cold | VL native |
|---|---|---|---|
| Small / metadata | 13.7× | 78× | 4.8× |
| Heavy / aggregations | 1,006× | 1,717× | 25.6× |
| Compute (c=100) | — | 101× | 19× (5.3× slower than cold proxy) |
Cold proxy at c=100 concurrency is 101× faster than Loki and 5.3× faster than VictoriaLogs native on the compute workload. The proxy's request coalescer collapses redundant parallel requests, which is why the cold-proxy number often beats the VL native number on concurrent read patterns.
Why this pattern works for Grafana
Grafana is already deeply opinionated around the Loki datasource and the Loki-style query path. Loki-VL-proxy keeps that client shape on the left while mapping requests to VictoriaLogs-aware internals on the right.
Labels and fields stay manageable
The proxy can expose underscore labels for Loki-safe query builder behavior while keeping dotted field semantics available through metadata modes and explicit mappings.
Patterns and Drilldown stay explicit
The Loki-compatible patterns endpoint is part of the supported read surface, with runtime gating and compatibility coverage for Grafana Logs Drilldown behavior.
Rules and alerts can stay visible
Read views for rules and alerts can be bridged through vmalert so Grafana does not lose those operational screens during the move.
Operators get their own control plane
The project ships route-aware metrics, structured logs, a packaged dashboard, and runbook-oriented docs instead of treating the proxy as a black box.
Where to go next
If this is the problem you are trying to solve, the next useful docs are the deployment guide, translation behavior, and observability model.