Generated by go run ./cmd/configdoc from the flags in cmd/proxy/main.go and the registry in internal/config. Do not edit by hand.

Configuration reference

Every command-line flag of the proxy (222), grouped by category, with the Helm value that sets it. Narrative guidance lives in configuration.md; the bounds on work are collected in limits-registry.md.

Helm passes any flag through extraArgs.<flag>; the chart sets a few of them from dedicated values, marked chart-managed.

cache

Flag	Type	Default	Helm value	Description
-cache-disabled	bool	false	extraArgs.cache-disabled	Disable the in-memory cache entirely (all requests pass through to the backend; useful for testing and cold-path measurement)
-cache-max	int	10000	extraArgs.cache-max	Maximum cache entries
-cache-max-bytes	int	defaultCacheMaxBytes	extraArgs.cache-max-bytes	Maximum in-memory L1 cache size in bytes
-cache-ttl	duration	1m0s	extraArgs.cache-ttl	Cache TTL for label/metadata queries
-compat-cache-enabled	bool	true	extraArgs.compat-cache-enabled	Enable the safe Tier0 compatibility-edge response cache for cacheable GET read endpoints
-compat-cache-max-percent	int	defaultCompatCachePercent	extraArgs.compat-cache-max-percent	Percent of -cache-max-bytes reserved for the Tier0 compatibility-edge cache (0 disables, max 50)
-disk-cache-compress	bool	true	extraArgs.disk-cache-compress	Gzip compression for disk cache
-disk-cache-flush-interval	duration	5s	extraArgs.disk-cache-flush-interval	Write buffer flush interval
-disk-cache-flush-size	int	100	extraArgs.disk-cache-flush-size	Flush write buffer after N entries
-disk-cache-max-bytes	int64	0	extraArgs.disk-cache-max-bytes	Maximum on-disk L2 cache size in bytes (0 = unlimited)
-disk-cache-min-ttl	duration	30s	extraArgs.disk-cache-min-ttl	Minimum entry TTL eligible for L2 disk cache writes (shorter TTL entries stay in-memory only). Empty label and label-value answers are cached for max(30s, this, -peer-write-through-min-ttl) so they replace older non-empty copies
-disk-cache-path	string	(empty)	persistence.* (chart-managed)	Path to L2 disk cache (bbolt). Empty disables.
-label-values-hot-limit	int	200	extraArgs.label-values-hot-limit	Default number of label values returned for empty-query browse requests when indexed cache is enabled
-label-values-index-max-entries	int	200000	extraArgs.label-values-index-max-entries	Maximum indexed values retained per tenant+label when indexed label-values cache is enabled
-label-values-index-persist-interval	duration	30s	extraArgs.label-values-index-persist-interval	How often to persist the in-memory label-values index snapshot to disk
-label-values-index-persist-path	string	(empty)	extraArgs.label-values-index-persist-path	Path to persisted label-values index snapshot JSON file. Empty disables persistence.
-label-values-index-startup-peer-warm-timeout	duration	5s	extraArgs.label-values-index-startup-peer-warm-timeout	Maximum time to wait for startup label-values index warm from peers when disk snapshot is stale or missing
-label-values-index-startup-stale-threshold	duration	1m0s	extraArgs.label-values-index-startup-stale-threshold	Treat on-disk label-values index snapshot older than this as stale and warm from peers before serving
-label-values-indexed-cache	bool	false	extraArgs.label-values-indexed-cache	Enable indexed browse cache for /loki/api/v1/label/{name}/values (hot subset first for empty-query requests)
-labels-cache-ttl	duration	0	extraArgs.labels-cache-ttl	Cache TTL for /labels and /label/{name}/values responses (default 5m). Keep-warm interval is derived automatically. 0 uses the default.
-labels-cache-warm	bool	true	extraArgs.labels-cache-warm	Warm the labels cache for the 1h/6h/24h/7d time-picker presets at startup and keep them warm in the background (every 75% of -labels-cache-ttl). Each refresh is a label-name scan of up to 7 days in VictoriaLogs; disable it on replicas that serve no interactive label pickers.
-query-range-adaptive-cooldown	duration	30s	extraArgs.query-range-adaptive-cooldown	Minimum time between adaptive query_range parallelism adjustments
-query-range-adaptive-max-parallel	int	8	extraArgs.query-range-adaptive-max-parallel	Maximum adaptive query_range window parallelism
-query-range-adaptive-min-parallel	int	2	extraArgs.query-range-adaptive-min-parallel	Minimum adaptive query_range window parallelism
-query-range-adaptive-parallel	bool	true	extraArgs.query-range-adaptive-parallel	Enable adaptive query_range window parallelism based on backend latency/error feedback
-query-range-align-windows	bool	true	extraArgs.query-range-align-windows	Align query_range split windows to fixed interval boundaries for overlap cache reuse
-query-range-background-warm	bool	true	extraArgs.query-range-background-warm	Warm failed query_range windows in background after partial response
-query-range-background-warm-max-windows	int	24	extraArgs.query-range-background-warm-max-windows	Maximum query_range windows warmed in background after partial response
-query-range-error-backoff-threshold	float64	0.02	extraArgs.query-range-error-backoff-threshold	Adaptive backoff threshold for backend fetch errors (0-1 ratio)
-query-range-expensive-hit-threshold	int64	2000	extraArgs.query-range-expensive-hit-threshold	Prefilter hit threshold above which a query_range window is treated as expensive
-query-range-expensive-max-parallel	int	1	extraArgs.query-range-expensive-max-parallel	Maximum window parallelism for expensive query_range windows
-query-range-freshness	duration	10m0s	extraArgs.query-range-freshness	Near-now freshness boundary; windows newer than now-freshness use recent cache TTL
-query-range-history-cache-ttl	duration	24h0m0s	extraArgs.query-range-history-cache-ttl	Cache TTL for historical query_range windows older than -query-range-freshness
-query-range-latency-backoff	duration	3s	extraArgs.query-range-latency-backoff	Adaptive backoff threshold: reduce parallelism when backend fetch latency exceeds this value
-query-range-latency-target	duration	1.5s	extraArgs.query-range-latency-target	Adaptive target backend fetch latency per window
-query-range-max-parallel	int	2	extraArgs.query-range-max-parallel	Maximum number of query_range windows fetched in parallel when adaptive parallelism is disabled
-query-range-partial-responses	bool	false	extraArgs.query-range-partial-responses	Allow partial query_range responses on retryable backend failures
-query-range-prefilter-index-stats	bool	true	extraArgs.query-range-prefilter-index-stats	Use /select/logsql/hits preflight to skip empty query_range windows before log fanout
-query-range-prefilter-min-windows	int	8	extraArgs.query-range-prefilter-min-windows	Minimum split windows required before enabling query_range prefilter
-query-range-recent-cache-ttl	duration	0	extraArgs.query-range-recent-cache-ttl	Cache TTL for near-now query_range windows (0 disables near-now result caching)
-query-range-split-interval	duration	1h0m0s	extraArgs.query-range-split-interval	Time window size used for query_range split/merge (for example 15m, 1h, 24h)
-query-range-stream-aware-batching	bool	true	extraArgs.query-range-stream-aware-batching	Reduce query_range batch parallelism for expensive windows estimated from prefilter hits
-query-range-windowing	bool	true	extraArgs.query-range-windowing	Enable query_range window splitting and window-level cache reuse for log queries
-recent-tail-refresh-enabled	bool	true	extraArgs.recent-tail-refresh-enabled	Bypass stale near-now cache hits and fetch latest backend data while preserving historical cache
-recent-tail-refresh-max-staleness	duration	2s	extraArgs.recent-tail-refresh-max-staleness	Maximum acceptable cache age for near-now (live-tail) requests before the response cache is bypassed and fresh data is fetched. Lower = fresher live tail, more backend load; raise to coalesce rapid refreshes.
-recent-tail-refresh-window	duration	2m0s	extraArgs.recent-tail-refresh-window	How close request end must be to now to enable near-now cache freshness bypass

cold storage

Flag	Type	Default	Helm value	Description
-cold-backend	string	(empty)	extraArgs.cold-backend	Cold storage backend URL (Victoria Lakehouse). Empty disables cold routing.
-cold-boundary	duration	168h0m0s	extraArgs.cold-boundary	Data older than this boundary routes to cold backend
-cold-enabled	bool	false	extraArgs.cold-enabled	Enable cold storage backend routing
-cold-manifest-refresh	duration	5m0s	extraArgs.cold-manifest-refresh	How often to refresh cold backend manifest range
-cold-overlap	duration	1h0m0s	extraArgs.cold-overlap	Overlap window around cold boundary where both hot and cold are queried
-cold-timeout	duration	30s	extraArgs.cold-timeout	Timeout for cold backend requests

compatibility

Flag	Type	Default	Helm value	Description
-backend-allow-unsupported-version	bool	false	extraArgs.backend-allow-unsupported-version	Allow startup with backend versions lower than -backend-min-version (at your own risk). Ignored when --backend-version-strict=true.
-backend-min-version	string	"v1.40.0"	extraArgs.backend-min-version	Minimum VictoriaLogs version considered fully supported at startup (first minor of the oldest supported line; v1.4x and v1.5x are supported)
-backend-version-strict	bool	false	extraArgs.backend-version-strict	When true, /health failure, non-2xx response, or missing/sub-min backend semver causes startup to fail. Default false (warn only). Overrides --backend-allow-unsupported-version when both are set.
-derived-fields	string	(empty)	extraArgs.derived-fields	name
-detected-level-body-scan	bool	true	extraArgs.detected-level-body-scan	Derive detected_level from the log line (JSON, logfmt, keywords) when a row has no stored level field, as Loki does; false uses stored level fields only with an unknown fallback
-drilldown-burst-max-fields	int	30	extraArgs.drilldown-burst-max-fields	maximum fields per coalesced VL burst call; fields beyond this cap form a second call
-drilldown-burst-window-ms	int	50	extraArgs.drilldown-burst-window-ms	time window in ms for coalescing concurrent Drilldown Fields per-field count queries into a single fused VL conditional-stats call (0 disables the coalescer)
-drilldown-field-batch-max-fields	int	6	extraArgs.drilldown-field-batch-max-fields	Deprecated, no effect: see -drilldown-field-batch-window-ms. Accepted so existing command lines keep working
-drilldown-field-batch-window-ms	int	100	extraArgs.drilldown-field-batch-window-ms	Deprecated, no effect: Logs Drilldown field breakdowns are answered exactly, one stats_query_range call each. Accepted so existing command lines keep working
-emit-structured-metadata	bool	true	extraArgs.emit-structured-metadata	Include Loki 3-tuple stream values [timestamp, line, metadata] in query responses
-error-response-message-field	bool	true	extraArgs.error-response-message-field	Add a message field with the error text to JSON error bodies. Grafana's Loki datasource displays that field (Loki itself answers errors as text/plain); false restores the previous {status, errorType, error} body.
-exact-parser-series-identity	bool	false	extraArgs.exact-parser-series-identity	Name the series of a metric over | json or | logfmt with the labels those parsers extracted, as Loki does, instead of the stream. Every such query is then evaluated from rows (bounded by -manual-metric-row-budget) rather than pushed down to VictoriaLogs stats, so it costs far more on wide ranges; | regexp and | pattern captures are always part of the identity because the query names them
-extra-label-fields	string	(empty)	extraArgs.extra-label-fields	host.id,custom.pipeline.processing
-field-mapping	string	(empty)	extraArgs.field-mapping	vl_field
-label-browse-extensions	string	"auto"	extraArgs.label-browse-extensions	error-response-message-field
-label-style	string	"underscores"	extraArgs.label-style	metadata-field-mode
-logql-dotted-names	string	"auto"	extraArgs.logql-dotted-names	label-browse-extensions
-metadata-default-lookback	duration	12h0m0s	extraArgs.metadata-default-lookback	Default time window for /labels, /label/{name}/values, and /series when the client omits start/end. 0 disables (unbounded scan).
-metadata-field-mode	string	"translated"	extraArgs.metadata-field-mode	translate-otel-attributes
-patterns-autodetect-from-queries	bool	false	extraArgs.patterns-autodetect-from-queries	Warm /loki/api/v1/patterns cache from successful query/query_range log responses (opt-in global autodetect)
-patterns-custom	string	(empty)	extraArgs.patterns-custom	patterns-custom-file
-patterns-custom-file	string	(empty)	extraArgs.patterns-custom-file	Path to custom Drilldown patterns file (JSON array or newline-separated text) loaded on startup
-patterns-enabled	bool	true	extraArgs.patterns-enabled	Enable /loki/api/v1/patterns endpoint (Grafana Logs Drilldown patterns)
-patterns-persist-interval	duration	30s	extraArgs.patterns-persist-interval	How often to persist in-memory patterns snapshots to disk
-patterns-persist-path	string	(empty)	extraArgs.patterns-persist-path	Path to persisted patterns snapshot JSON file. Empty disables persistence.
-patterns-startup-peer-warm-timeout	duration	5s	extraArgs.patterns-startup-peer-warm-timeout	Maximum time to wait for startup patterns snapshot warm from peers
-patterns-startup-stale-threshold	duration	1m0s	extraArgs.patterns-startup-stale-threshold	Treat on-disk patterns snapshot older than this as stale and warm from peers before serving
-stream-fields	string	(empty)	extraArgs.stream-fields	app,env,namespace
-tail.allowed-origins	string	(empty)	extraArgs.tail.allowed-origins	Comma-separated WebSocket Origin allowlist for /loki/api/v1/tail. Empty denies browser origins.
-tail.mode	string	"auto"	extraArgs.tail.mode	Tail streaming mode: auto (native with synthetic fallback), native, or synthetic
-translate-otel-attributes	bool	true	extraArgs.translate-otel-attributes	Translate known OTel semantic convention labels from underscore to dotted form in upstream queries (set false to preserve client label names)

limits

Flag	Type	Default	Helm value	Description
-backend-heavy-query-min-range	duration	6 * time.Hour	extraArgs.backend-heavy-query-min-range	Time range from which VictoriaLogs stats, hits and unbounded raw calls count as heavy for -backend-max-concurrent-heavy-queries, and metadata listings count as long-range for -backend-max-concurrent-metadata-scans. Must be > 0
-backend-heavy-query-queue-wait	duration	20 * time.Second	extraArgs.backend-heavy-query-queue-wait	How long the heavy VictoriaLogs calls of one request wait, together, for -backend-max-concurrent-heavy-queries slots, and how long each long-range metadata scan waits for a -backend-max-concurrent-metadata-scans slot, before the request fails with 429. 0 rejects immediately when all slots are busy
-backend-max-buffered-response-bytes	int	67108864	extraArgs.backend-max-buffered-response-bytes	Maximum bytes the proxy reads from one VictoriaLogs response it has to evaluate itself (buffered stats, volume and binary-operand responses, and the encoded metric result). Exceeding it returns HTTP 502 naming this flag instead of a truncated result. Proxy memory grows with this value times the concurrent requests that buffer a response. 0 uses the built-in default of 64 MiB
-backend-max-concurrent-heavy-queries	int	2	extraArgs.backend-max-concurrent-heavy-queries	Maximum concurrent heavy VictoriaLogs calls per replica: raw-row metric fetches (any /select/logsql/query bound above 10000 rows, which includes a log query whose limit is higher), and stats or hits calls spanning at least -backend-heavy-query-min-range or finer than 11000 buckets. Further heavy calls queue for -backend-heavy-query-queue-wait, then fail with 429 "too many outstanding requests". VictoriaLogs lets each stats pipe use up to 40% of its allowed memory, so the default of 2 keeps concurrent stats state within its memory budget. 0 disables the limiter
-backend-max-concurrent-metadata-scans	int	8	extraArgs.backend-max-concurrent-metadata-scans	Ceiling of the adaptive limit on concurrent long-range VictoriaLogs metadata scans per replica: stream_field_names, stream_field_values, field_names, field_values and streams calls spanning at least -backend-heavy-query-min-range or without a time range, and the day bucket scans of the label inventory for such listings. Selects VictoriaLogs runs for others (read from its /metrics) count against the limit; it starts at 2, grows while scans that used it stay within -backend-metadata-scan-latency-tolerance of their no-load duration, shrinks on slow scans or backend failures, and no scan starts while VictoriaLogs lacks -backend-metadata-scan-memory-headroom. Each scan waits at most -backend-heavy-query-queue-wait, then the request fails with 429; background inventory refreshes skip instead of waiting. 0 disables the limiter
-backend-metadata-scan-latency-tolerance	float64	1.5	extraArgs.backend-metadata-scan-latency-tolerance	How many times its no-load duration (per row when the rows are known) a long-range metadata scan that ran beside others may take before the adaptive limit shrinks by 20%. Must be >= 1; 0 uses the default
-backend-metadata-scan-memory-headroom	float64	0.4	extraArgs.backend-metadata-scan-memory-headroom	Fraction of the memory available to VictoriaLogs (vm_available_memory_bytes on its /metrics) that long-range metadata scans must leave free: a scan is admitted only while the memory VictoriaLogs has in use, plus the estimated cost of in-flight scans, of the selects it runs for others and of this one, stays below 1 minus this fraction. Costs are learned per endpoint, range and tenant from the memory growth while scans ran; a listing never measured runs alone. 0 disables the memory gate (latency and failure feedback remain)
-backend-min-concurrent-metadata-scans	int	1	extraArgs.backend-min-concurrent-metadata-scans	Floor of the adaptive limit on concurrent long-range VictoriaLogs metadata scans per replica: latency and failure feedback never shrink the limit below it, and below it a replica may start a scan while others' long work uses up to a quarter of VictoriaLogs' select slots. VictoriaLogs' full select slots, memory headroom and a silent /metrics still hold scans back. Must be <= -backend-max-concurrent-metadata-scans; 0 uses the default
-binary-metric-max-arrays	int	2000000	extraArgs.binary-metric-max-arrays	Maximum JSON arrays one binary metric expression may allocate while joining operands. 0 uses the built-in default of 2000000
-binary-metric-max-operand-bytes	int	268435456	extraArgs.binary-metric-max-operand-bytes	Maximum bytes of operand responses one binary metric expression may capture. 0 uses the built-in default of 256 MiB
-default-max-query-length	duration	0	extraArgs.default-max-query-length	Default maximum query time range enforced for all tenants unless overridden by per-tenant limits (0 = unlimited, matches Loki default)
-detected-fields-max-scan-lines	int	2000	extraArgs.detected-fields-max-scan-lines	Maximum log lines the detected_fields / detected_field values scan reads per request. 0 uses the built-in default of 2000
-drilldown-max-stats-buckets	int	120	extraArgs.drilldown-max-stats-buckets	Deprecated, no effect: Logs Drilldown breakdowns are answered on the requested step, as Loki answers them. Accepted so existing command lines keep working
-http-conn-max-age	duration	10m0s	extraArgs.http-conn-max-age	Maximum lifetime for downstream HTTP/1.x keepalive connections before responding with Connection: close (0 disables)
-http-conn-max-age-jitter	duration	2m0s	extraArgs.http-conn-max-age-jitter	Jitter applied to downstream HTTP/1.x connection age rotation to avoid synchronized reconnects
-http-conn-max-requests	int	256	extraArgs.http-conn-max-requests	Maximum downstream HTTP/1.x requests served on one keepalive connection before responding with Connection: close (0 disables)
-http-conn-overload-max-age	duration	1m30s	extraArgs.http-conn-overload-max-age	Shorter downstream HTTP/1.x connection lifetime applied while query_range backpressure is active (0 disables overload shedding)
-http-max-body-bytes	int64	10485760	extraArgs.http-max-body-bytes	HTTP max request body size (default: 10MB)
-http-max-header-bytes	int	1048576	extraArgs.http-max-header-bytes	HTTP max header size (default: 1MB)
-label-filter-refill-max-pages	int	8	extraArgs.label-filter-refill-max-pages	Loki-compatible profile: more pages of at most limit rows a log query reads when a Loki label filter on a log line key no earlier stage exposes dropped rows VictoriaLogs matched, so the page still holds limit lines. A response reads at most (1 + N) x limit rows; 0 reads no further page, and such a page can return fewer lines than the limit.
-label-values-max-response-bytes	int	67108864	extraArgs.label-values-max-response-bytes	Maximum bytes of the VictoriaLogs answer to a /loki/api/v1/label/{name}/values request: one response, or the size the merged listing would have as one response when the metadata inventory lists it from time buckets. Above it the request fails like Loki's querier above grpc_server_max_send_msg_size: HTTP 500 rpc error: code = ResourceExhausted desc = grpc: trying to send message larger than max (N vs. LIMIT) naming this flag, and nothing is cached. Per tenant as label_values_max_response_bytes in -tenant-limits and -tenant-default-limits. 0 uses the built-in default of 64 MiB
-manual-range-metric-row-limit	int	1000000	extraArgs.manual-range-metric-row-limit	Maximum log rows fetched per manual range-metric compatibility call (rate, count_over_time, etc.). Lower values bound memory at the cost of result truncation for high-cardinality queries.
-max-concurrent	int	100	extraArgs.max-concurrent	Maximum concurrent requests allowed through the proxy (0 disables)
-max-entries-limit-per-query	int	10000	extraArgs.max-entries-limit-per-query	Loki's max_entries_limit_per_query: a log query asking for more lines fails with Loki's 400 (see -max-entries-limit-per-query-cap); label values requests above it are capped. Per tenant through -tenant-limits and -tenant-default-limits. 0 uses the built-in default of 10000
-max-entries-limit-per-query-cap	bool	false	extraArgs.max-entries-limit-per-query-cap	Lower a log query limit above max_entries_limit_per_query to that value instead of rejecting it with Loki's 400 (the proxy's behaviour before 1.93; Loki rejects)
-max-lines	int	1000	extraArgs.max-lines	Default max lines per query
-max-metadata-cache-freshness	duration	24h0m0s	extraArgs.max-metadata-cache-freshness	Loki max_metadata_cache_freshness, applied to all tenants: a /labels, /label/{name}/values or /series request that ends within this window of now does not reuse a cached answer older than -recent-tail-refresh-max-staleness, so streams written in the window appear like in Loki. Sealed non-empty inventory buckets still come from the cache; the newest minute, buckets due for revalidation and a row count over each run of empty buckets (stream and field filters only; cheap for * and stream filters, but with a field filter it reads the filtered column of every row in the run's range) are read live. A bucket stored empty with rows that lack the listed field follows the normal schedule. 0 keeps the previous caching for every range.
-max-query-length-bytes	int	131072	extraArgs.max-query-length-bytes	Maximum LogQL query string length in bytes. The default matches Loki's syntax.maxInputSize (131072), so the proxy rejects only what Loki rejects; lower it to reject long queries earlier. 0 uses the built-in default
-max-stats-query-series	int	0	extraArgs.max-stats-query-series	Maximum number of series returned by stats metric queries (count_over_time, rate, bytes_rate). 0 = built-in default of 500, matching the Drilldown maxDrilldownSeries cap and the documented known-limit for high-cardinality fields (trace_id, *_id, churn-heavy pod naming) where each value appears only 1-2× in the window. The previous 5000 default returned 10× more sparse series than Drilldown can render and 10× more bytes for the same UX, while leaving the door open to VL OOMs on real workloads with 100k+ cardinality.
-max-zero-fill-buckets	int	32768	extraArgs.max-zero-fill-buckets	Maximum buckets the proxy zero-fills in a metric response. 0 uses the built-in default of 32768
-metadata-inventory-parallelism	int	4	extraArgs.metadata-inventory-parallelism	Label names and values (/labels, /label/{name}/values, detected field names) are listed from a time-bucketed inventory: day, hour, 5-minute and minute buckets cached in the read cache (memory, disk and peers) and merged, so a window moved by seconds reads only its edges from VictoriaLogs. This is how many bucket listings one request may have in flight. 0 turns the inventory off, making every listing one VictoriaLogs call over the whole range
-multi-tenant-max-fanout	int	64	extraArgs.multi-tenant-max-fanout	Maximum tenants one multi-tenant request may fan out to; more returns HTTP 400 naming this flag. 0 uses the built-in default of 64
-multi-tenant-max-merged-response-bytes	int	33554432	extraArgs.multi-tenant-max-merged-response-bytes	Maximum bytes of a merged multi-tenant response; more returns HTTP 413 naming this flag. 0 uses the built-in default of 32 MiB
-ordered-json-metric-max-bytes	int64	1073741824	extraArgs.ordered-json-metric-max-bytes	Safety cap on the VictoriaLogs raw rows response read, and the response built, by the proxy-side ordered JSON metric evaluator (0 = default 1 GiB, no upper bound). Exceeding it rejects the query instead of returning partial results. Grafana logs volume shapes are computed from VictoriaLogs stats buckets and do not read raw rows.
-patterns-max-backend-rows	int	20000	extraArgs.patterns-max-backend-rows	Maximum log lines /patterns reads from VictoriaLogs for one request. 0 uses the built-in default of 20000
-patterns-second-pass-max-rows	int	8000	extraArgs.patterns-second-pass-max-rows	Maximum log lines the /patterns second pass reads when the first pass mined too few patterns. 0 uses the built-in default of 8000
-patterns-second-pass-max-windows	int	8	extraArgs.patterns-second-pass-max-windows	Maximum windows the /patterns second pass re-reads. 0 uses the built-in default of 8
-rate-limit-burst	int	100	extraArgs.rate-limit-burst	Per-client burst size for request rate limiting (0 disables burst bucket)
-rate-limit-per-second	float64	50	extraArgs.rate-limit-per-second	Per-client request rate limit in requests per second (0 disables)
-stats-query-range-concurrency	int	0	extraArgs.stats-query-range-concurrency	Maximum concurrent stats_query_range calls to VictoriaLogs. Drilldown Fields fires ~30 in parallel; capping prevents CPU storms. 0 = built-in default of 4.
-stats-query-range-inter-query-delay-ms	int	200	extraArgs.stats-query-range-inter-query-delay-ms	minimum pause in ms between consecutive individual VL stats_query_range calls: the semaphore slot is held for this duration after each call completes, spreading the drilldown burst over time and reducing VL CPU spikes (0 disables)

observability

Flag	Type	Default	Helm value	Description
-deployment-environment	string	(empty)	extraArgs.deployment-environment	OpenTelemetry deployment.environment.name for logs and OTLP metrics
-host-proc-root	string	"/proc"	extraArgs.host-proc-root	Filesystem root for host-scope /proc reads (stat, meminfo, pressure/{cpu,memory,io}). Set to /host/proc when running with the chart's surgical hostPath mounts. Defaults to /proc.
-log-buffered	bool	true	extraArgs.log-buffered	Write logs in the background to avoid slowing down requests under high load
-log-level	string	"info"	extraArgs.log-level	Log level: debug, info, warn, error
-log-rate-threshold	int	10	extraArgs.log-rate-threshold	When traffic exceeds this rate (req/s), replace per-request logs with periodic summaries. Errors are always logged.
-log-request-sample-rate	int	0	extraArgs.log-request-sample-rate	Sample rate for per-request access logs on successful (2xx) responses. 0 or 1 logs every request. N>1 logs 1 in every N requests. 4xx/5xx are always logged.
-log-stats-interval	duration	10s	extraArgs.log-stats-interval	How often to print a request statistics summary (total, errors, latency, cache rate)
-metrics-listen	string	(empty)	extraArgs.metrics-listen	Optional dedicated address for the /metrics endpoint. When empty AND --server.register-instrumentation=true, /metrics is served on --listen (back-compat). When non-empty AND --server.register-instrumentation=true, /metrics is served on this dedicated listener.
-metrics.export-sensitive-labels	bool	false	extraArgs.metrics.export-sensitive-labels	Export per-tenant and per-client identity metrics on /metrics and OTLP
-metrics.max-clients	int	256	extraArgs.metrics.max-clients	Maximum unique client labels retained in exported metrics before collapsing into overflow
-metrics.max-tenants	int	256	extraArgs.metrics.max-tenants	Maximum unique tenant labels retained in exported metrics before collapsing into overflow
-metrics.trust-proxy-headers	bool	false	extraArgs.metrics.trust-proxy-headers	Trust X-Grafana-User and X-Forwarded-For when deriving per-client metrics labels
-otel-service-instance-id	string	(empty)	extraArgs.otel-service-instance-id	OpenTelemetry service.instance.id for logs and OTLP metrics
-otel-service-name	string	"loki-vl-proxy"	extraArgs.otel-service-name	OpenTelemetry service.name for logs and OTLP metrics
-otel-service-namespace	string	(empty)	extraArgs.otel-service-namespace	OpenTelemetry service.namespace for logs and OTLP metrics
-otlp-compression	string	"none"	extraArgs.otlp-compression	OTLP compression: none, gzip, zstd
-otlp-endpoint	string	(empty)	extraArgs.otlp-endpoint	OTLP HTTP endpoint (e.g., http://otel-collector:4318/v1/metrics)
-otlp-headers	string	(empty)	extraArgs.otlp-headers	Comma-separated OTLP HTTP headers in key=value form
-otlp-interval	duration	30s	extraArgs.otlp-interval	OTLP push interval
-otlp-timeout	duration	10s	extraArgs.otlp-timeout	OTLP HTTP request timeout
-otlp-tls-skip-verify	bool	false	extraArgs.otlp-tls-skip-verify	Skip TLS verification for OTLP endpoint
-proc-root	string	"/proc"	extraArgs.proc-root	Filesystem root for self/container-scope /proc reads (self/status, self/io, self/stat, self/fd, net/dev). Back-compat: if --host-proc-root is left at its default, this value also seeds the host-scope root.

peer cache

Flag	Type	Default	Helm value	Description
-peer-auth-token	string	(empty)	extraArgs.peer-auth-token	Shared token required on /_cache/get and /_cache/set peer-cache requests when set
-peer-discovery	string	(empty)	peerCache.* (chart-managed)	dns
-peer-dns	string	(empty)	peerCache.* (chart-managed)	dns
-peer-hot-read-ahead-enabled	bool	false	extraArgs.peer-hot-read-ahead-enabled	Enable bounded hot read-ahead from peer hot index to prewarm local shadows
-peer-hot-read-ahead-error-backoff	duration	15s	extraArgs.peer-hot-read-ahead-error-backoff	Base read-ahead cooldown applied after peer/index errors
-peer-hot-read-ahead-interval	duration	30s	extraArgs.peer-hot-read-ahead-interval	Base interval for periodic peer hot read-ahead pulls
-peer-hot-read-ahead-jitter	duration	5s	extraArgs.peer-hot-read-ahead-jitter	Random jitter added to peer hot read-ahead interval
-peer-hot-read-ahead-max-bytes-per-interval	int64	8388608	extraArgs.peer-hot-read-ahead-max-bytes-per-interval	Maximum bytes prefetched per interval
-peer-hot-read-ahead-max-concurrency	int	4	extraArgs.peer-hot-read-ahead-max-concurrency	Maximum concurrent hot-index and prefetch peer operations
-peer-hot-read-ahead-max-keys-per-interval	int	64	extraArgs.peer-hot-read-ahead-max-keys-per-interval	Maximum number of hot keys prefetched per interval
-peer-hot-read-ahead-max-object-bytes	int	262144	extraArgs.peer-hot-read-ahead-max-object-bytes	Maximum object size eligible for hot read-ahead
-peer-hot-read-ahead-min-ttl	duration	30s	extraArgs.peer-hot-read-ahead-min-ttl	Minimum remaining TTL required for hot read-ahead candidates
-peer-hot-read-ahead-tenant-fair-share	int	50	extraArgs.peer-hot-read-ahead-tenant-fair-share	Maximum per-tenant share (percent) of key budget in fairness pass
-peer-hot-read-ahead-top-n	int	256	extraArgs.peer-hot-read-ahead-top-n	Number of top hot keys requested from each peer hot index
-peer-http-url	string	(empty)	peerCache.* (chart-managed)	http
-peer-insecure-ip-allowlist	bool	false	extraArgs.peer-insecure-ip-allowlist	When true, allow peer cache requests based on source IP membership alone (legacy behavior). Default false: a shared --peer-auth-token is required when peer discovery is configured.
-peer-self	string	(empty)	peerCache.* (chart-managed)	10.0.0.1:3100
-peer-self-az	string	(empty)	extraArgs.peer-self-az	us-east-1a
-peer-srv	string	(empty)	peerCache.* (chart-managed)	srv
-peer-static	string	(empty)	peerCache.* (chart-managed)	static
-peer-timeout	duration	2s	extraArgs.peer-timeout	Timeout for peer-cache fetch requests to owner peers
-peer-write-through	bool	true	extraArgs.peer-write-through	Push cache writes from non-owner peers to owner peers for warmer distributed cache under skewed traffic
-peer-write-through-min-ttl	duration	30s	extraArgs.peer-write-through-min-ttl	Minimum TTL eligible for peer owner write-through pushes. Empty label and label-value answers are cached for max(30s, this, -disk-cache-min-ttl) so they replace older non-empty copies

security

Flag	Type	Default	Helm value	Description
-cb-fail-threshold	int	5	extraArgs.cb-fail-threshold	Circuit breaker: failures within -cb-window-duration before opening
-cb-open-duration	duration	10s	extraArgs.cb-open-duration	Circuit breaker: how long to stay open before allowing probe requests
-cb-window-duration	duration	30s	extraArgs.cb-window-duration	Circuit breaker: sliding window for failure counting; failures older than this are discarded
-coalescer-disabled	bool	false	extraArgs.coalescer-disabled	Disable request coalescing (singleflight); every concurrent request makes its own backend call — useful with -cache-disabled to measure raw translation overhead
-debug-log-raw-queries	bool	false	extraArgs.debug-log-raw-queries	When true, debug logs include raw LogQL/LogsQL and backend params verbatim. Default false (redacted to sha256+len).
-forward-authorization	bool	false	extraArgs.forward-authorization	Forward Authorization header to VL backend (equivalent to including Authorization in -forward-headers)
-forward-cookies	string	(empty)	extraArgs.forward-cookies	Comma-separated list of cookie names to forward to VL backend
-forward-headers	string	(empty)	extraArgs.forward-headers	Comma-separated list of HTTP headers to forward to VL backend
-server.admin-auth-token	string	(empty)	extraArgs.server.admin-auth-token	Bearer token required for admin/debug endpoints when set
-server.enable-pprof	bool	false	extraArgs.server.enable-pprof	Expose /debug/pprof/* handlers
-server.enable-query-analytics	bool	false	extraArgs.server.enable-query-analytics	Expose /debug/queries query analytics
-server.metrics-max-concurrency	int	1	extraArgs.server.metrics-max-concurrency	Maximum concurrent /metrics scrapes served at once (0 disables the cap)
-server.register-instrumentation	bool	false	extraArgs.server.register-instrumentation	Register instrumentation handlers such as /metrics. Default false (BREAKING in v1.56.0; was true). Set true and optionally pair with --metrics-listen for a dedicated scrape port. The Helm chart sets this to true automatically so ServiceMonitor scrapes keep working without operator action.
-tls-cert-file	string	(empty)	extraArgs.tls-cert-file	TLS certificate file for HTTPS server
-tls-client-ca-file	string	(empty)	extraArgs.tls-client-ca-file	CA certificate file used to verify HTTPS client certificates
-tls-key-file	string	(empty)	extraArgs.tls-key-file	TLS private key file for HTTPS server
-tls-require-client-cert	bool	false	extraArgs.tls-require-client-cert	Require and verify HTTPS client certificates

server

Flag	Type	Default	Helm value	Description
-admin-listen	string	"127.0.0.1:3101"	extraArgs.admin-listen	Address for admin/debug endpoints (/admin/, /debug/) when --server.admin-auth-token is empty. Loopback by default so the binary boots safely with no flags. Ignored when --server.admin-auth-token is set — admin endpoints then ride the main --listen address.
-alerts-backend	string	(empty)	extraArgs.alerts-backend	Optional alert backend URL for /alerts passthrough (defaults to -ruler-backend when unset)
-backend	string	"http://localhost:9428"	extraArgs.backend	VictoriaLogs backend URL
-backend-basic-auth	string	(empty)	extraArgs.backend-basic-auth	Basic auth for VL backend (user:password)
-backend-compression	string	"auto"	extraArgs.backend-compression	Backend HTTP compression preference: auto, gzip, zstd, none
-backend-default-msg-value	string	(empty)	extraArgs.backend-default-msg-value	VictoriaLogs -defaultMsgValue when it is customized. Rows whose _msg is empty, starts with VictoriaLogs' default "missing _msg field" text, or equals this value get their log line rebuilt as a JSON object of the row's non-stream fields
-backend-tls-skip-verify	bool	false	extraArgs.backend-tls-skip-verify	Skip TLS verification for VL backend
-go-gc-percent	int	200	extraArgs.go-gc-percent	GOGC target percentage. Higher values reduce GC frequency at the cost of higher peak RSS. Set to -1 to use Go runtime default (100). Ignored when GOGC env var is already set.
-go-mem-limit	int64	0	extraArgs.go-mem-limit	Explicit GOMEMLIMIT in bytes. Overrides -go-mem-limit-percent. 0 = use percentage or GOMEMLIMIT env var.
-go-mem-limit-percent	int	85	extraArgs.go-mem-limit-percent	Percentage of the detected container memory limit (cgroups) to set as GOMEMLIMIT. 0 disables auto-detection. Ignored when GOMEMLIMIT env var or -go-mem-limit is set.
-listen	string	":3100"	extraArgs.listen	Address to listen on (Loki-compatible frontend)
-response-compression	string	(empty)	extraArgs.response-compression	Response compression codec: auto, gzip, none (default: auto)
-response-compression-min-bytes	int	defaultResponseCompressionMinBytes	extraArgs.response-compression-min-bytes	Minimum response size before frontend compression starts (0 compresses any size)
-response-gzip	bool	true	extraArgs.response-gzip	Deprecated: enable compressed responses for clients that accept them; prefer -response-compression
-ruler-backend	string	(empty)	extraArgs.ruler-backend	Optional alert/ruler backend URL for /rules passthrough (for example vmalert)
-stream-response	bool	false	extraArgs.stream-response	Stream log responses via chunked transfer encoding
-warmup-max-jitter	duration	0	extraArgs.warmup-max-jitter	Maximum random delay before label cache warmup starts. Spread this across a fleet (e.g. 10s for ≥3 instances) to prevent all proxies hammering VL simultaneously on restart.

tenancy

Flag	Type	Default	Helm value	Description
-auth.enabled	bool	false	extraArgs.auth.enabled	Require X-Scope-OrgID on query requests. When false, requests without a tenant header use the backend default tenant.
-forward-tenant-header	bool	true	extraArgs.forward-tenant-header	Forward the per-tenant X-Scope-OrgID header to the upstream backend. Safe for VictoriaLogs (ignores it). Required for Victoria Lakehouse native tenant routing.
-require-tenant-header	bool	false	extraArgs.require-tenant-header	Reject requests missing X-Scope-OrgID with HTTP 401. Independent of -auth.enabled; use when you want tenant enforcement without full auth.
-tenant-default-limits	string	(empty)	extraArgs.tenant-default-limits	query_timeout
-tenant-label	string	(empty)	extraArgs.tenant-label	VL field name for label-based tenant routing. When set, X-Scope-OrgID values are injected as {<tenant-label>="<orgID>"} into VL queries instead of AccountID/ProjectID headers. Use when all data is under VL default tenant (0:0). Explicit -tenant-map entries take priority. Env: TENANT_LABEL
-tenant-limits	string	(empty)	extraArgs.tenant-limits	otlp-endpoint
-tenant-limits-allow-publish	string	(empty)	extraArgs.tenant-limits-allow-publish	Comma-separated limit fields published on /config/tenant/v1/limits and /loki/api/v1/drilldown-limits
-tenant-map	string	(empty)	extraArgs.tenant-map	org-name
-tenant-map-file	string	(empty)	extraArgs.tenant-map-file	Path to YAML or JSON file containing the tenant map. Hot-reloaded on SIGHUP and automatically when the file changes (see -tenant-map-reload-interval). Supports Kubernetes ConfigMap volumes.
-tenant-map-reload-interval	duration	30s	extraArgs.tenant-map-reload-interval	How often to poll -tenant-map-file for mtime changes. Set to 0 to disable polling.
-tenant.allow-global	bool	false	extraArgs.tenant.allow-global	*

timeouts

Flag	Type	Default	Helm value	Description
-backend-timeout	duration	2m0s	extraArgs.backend-timeout	Timeout for non-streaming requests to the VictoriaLogs backend. The remaining budget is also passed to VictoriaLogs as its per-query timeout argument, so VictoriaLogs stops work the proxy has given up on
-backend-version-check-timeout	duration	5s	extraArgs.backend-version-check-timeout	Timeout for startup backend version compatibility check
-drilldown-scan-timeout	duration	5s	extraArgs.drilldown-scan-timeout	Per-request timeout for the detected_fields / detected_field_values log scan path. Caps the time a single Drilldown panel can spend scanning logs with a parser filter. 0 disables the cap (use VL's natural response time).
-http-idle-timeout	duration	2m0s	extraArgs.http-idle-timeout	HTTP server idle timeout
-http-read-header-timeout	duration	10s	extraArgs.http-read-header-timeout	HTTP server read header timeout
-http-read-timeout	duration	30s	extraArgs.http-read-timeout	HTTP server read timeout
-http-write-timeout	duration	2m0s	extraArgs.http-write-timeout	HTTP server write timeout
-query-range-window-timeout	duration	20s	extraArgs.query-range-window-timeout	Per-window backend timeout budget for query_range window fetches (0 disables)