Use Feuer Disk-Cache

LICENSE-3rdparty.csv

@@ -264,6 +264,11 @@ fail,https://github.com/tikv/fail-rs,Apache-2.0,The TiKV Project Developers
 fancy-regex,https://github.com/fancy-regex/fancy-regex,MIT,"Raph Levien <raph@google.com>, Robin Stocker <robin@nibor.org>, Keith Hall <keith.hall@available.systems>"
 fastdivide,https://github.com/fulmicoton/fastdivide,zlib-acknowledgement OR MIT,Paul Masurel <paul.masurel@gmail.com>
 fastrand,https://github.com/smol-rs/fastrand,Apache-2.0 OR MIT,Stjepan Glavina <stjepang@gmail.com>
+feuer,https://github.com/PSeitz/feuer,MIT,Feuer Project Authors
+feuer-historian,https://github.com/PSeitz/feuer,MIT,Feuer Project Authors
+feuer-memory,https://github.com/PSeitz/feuer,MIT,Feuer Project Authors
+feuer-storage,https://github.com/PSeitz/feuer,MIT,Feuer Project Authors
+feuer-types,https://github.com/PSeitz/feuer,MIT,Feuer Project Authors
 ff,https://github.com/zkcrypto/ff,MIT OR Apache-2.0,"Sean Bowe <ewillbefull@gmail.com>, Jack Grigg <thestr4d@gmail.com>"
 fiat-crypto,https://github.com/mit-plv/fiat-crypto,MIT OR Apache-2.0 OR BSD-1-Clause,Fiat Crypto library authors <jgross@mit.edu>
 find-msvc-tools,https://github.com/rust-lang/cc-rs,MIT OR Apache-2.0,The find-msvc-tools Authors
@@ -363,6 +368,7 @@ inherent,https://github.com/dtolnay/inherent,MIT OR Apache-2.0,David Tolnay <dto
 inout,https://github.com/RustCrypto/utils,MIT OR Apache-2.0,RustCrypto Developers
 instant,https://github.com/sebcrozet/instant,BSD-3-Clause,sebcrozet <developer@crozet.re>
 inventory,https://github.com/dtolnay/inventory,MIT OR Apache-2.0,David Tolnay <dtolnay@gmail.com>
+io-uring,https://github.com/tokio-rs/io-uring,MIT OR Apache-2.0,quininer <quininer@live.com>
 ipcrypt-rs,https://github.com/jedisct1/rust-ipcrypt2,ISC,Frank Denis <github@pureftpd.org>
 ipnet,https://github.com/krisprice/ipnet,MIT OR Apache-2.0,Kris Price <kris@krisprice.nz>
 ipnetwork,https://github.com/achanda/ipnetwork,MIT OR Apache-2.0,"Abhishek Chanda <abhishek.becs@gmail.com>, Linus Färnstrand <faern@faern.net>"
@@ -431,6 +437,7 @@ minimal-lexical,https://github.com/Alexhuszagh/minimal-lexical,MIT OR Apache-2.0
 miniserde,https://github.com/dtolnay/miniserde,MIT OR Apache-2.0,David Tolnay <dtolnay@gmail.com>
 miniz_oxide,https://github.com/Frommi/miniz_oxide/tree/master/miniz_oxide,MIT OR Zlib OR Apache-2.0,"Frommi <daniil.liferenko@gmail.com>, oyvindln <oyvindln@users.noreply.github.com>, Rich Geldreich richgel99@gmail.com"
 mio,https://github.com/tokio-rs/mio,MIT,"Carl Lerche <me@carllerche.com>, Thomas de Zeeuw <thomasdezeeuw@gmail.com>, Tokio Contributors <team@tokio.rs>"
+mixtrics,https://github.com/foyer-rs/mixtrics,Apache-2.0,MrCroxx <mrcroxx@outlook.com>
 mockall,https://github.com/asomers/mockall,MIT OR Apache-2.0,Alan Somers <asomers@gmail.com>
 mockall_derive,https://github.com/asomers/mockall,MIT OR Apache-2.0,Alan Somers <asomers@gmail.com>
 mrecordlog,https://github.com/quickwit-oss/mrecordlog,MIT,The mrecordlog Authors

config/quickwit.yaml

@@ -199,9 +199,13 @@ indexer:
 #   # service. Searchers require at least one `metastore_read_replica` node at
 #   # startup and do not fall back to the primary metastore.
 #   use_metastore_read_replica: false
+#   # Feuer fast-field RAM cache. Default 1G. Omitted while disk_cache
+#   # is set disables this cache; set a capacity explicitly to keep both.
 #   fast_field_cache_capacity: 1G
-#   split_footer_cache_capacity: 500M
-#   partial_request_cache_capacity: 64M
+#   # Feuer memory caches (also accept the legacy *_cache_capacity keys).
+#   # Set to zero to disable. Add disk settings as shown below for a disk tier.
+#   partial_request_cache: 64M
+#   predicate_cache: 256M
 #   max_num_concurrent_split_streams: 100
 #   max_num_concurrent_split_searches: 100
 #   aggregation_memory_limit: 500M
@@ -210,6 +214,26 @@ indexer:
 #      max_num_bytes: 1G
 #      max_num_splits: 10000
 #      num_concurrent_downloads: 1
+#   # Feuer cache for split footer and body ranges. Omitted or null disables it.
+#   # Disk-cache configurations require Linux, including disk_capacity: 0.
+#   # Feuer handles disk alignment internally; memory capacity is a soft target.
+#   # Shared directory; each cache has a distinct backing file and lock.
+#   # Per-cache path overrides remain supported.
+#   disk_cache_directory: /quickwit/qwdata/feuer-v1
+#   disk_cache:
+#     disk_capacity: 1500GiB
+#     memory_capacity: 15GiB
+#   # Alternatively, replace the scalar result-cache settings above with:
+#   # Instances share disk I/O queues, but have independent budgets and files.
+#   # Fixed filenames: split_cache, partial_response_cache, predicate_cache.
+#   # memory_capacity (alias capacity) is the RAM budget.
+#   # Explicit policy and nonempty virtual_caches are unsupported with Feuer.
+#   partial_request_cache:
+#     memory_capacity: 64MiB
+#     disk_capacity: 20GiB
+#   predicate_cache:
+#     memory_capacity: 256MiB
+#     disk_capacity: 100GiB
 # -------------------------------- Jaeger settings --------------------------------
 
 jaeger:

docs/configuration/node-config.md

@@ -310,14 +310,18 @@ This section contains the configuration options for a Searcher.
 | --- | --- | --- |
 | `aggregation_memory_limit` | Controls the maximum amount of memory that can be used for aggregations before aborting. This limit is per searcher node. A node may run concurrent queries, which share the limit. The first query that will hit the limit will be aborted and frees its memory. It is used to prevent excessive memory usage during the aggregation phase, which can lead to performance degradation or crashes. | `500M`|
 | `aggregation_bucket_limit` | Determines the maximum number of buckets returned to the client. | `65000` |
-| `fast_field_cache_capacity` | Fast field in memory cache capacity on a Searcher. If your filter by dates, run aggregations, range queries, or even for tracing, it might worth increasing this parameter. The [metrics](../reference/metrics.md) starting by `quickwit_cache_fastfields_cache` can help you make an informed choice when setting this value. | `1G` |
-| `split_footer_cache_capacity` | Split footer in memory cache (it is essentially the hotcache) capacity on a Searcher.| `500M` |
-| `partial_request_cache_capacity` | Partial request in memory cache capacity on a Searcher. Cache intermediate state for a request, possibly making subsequent requests faster. It can be disabled by setting the size to `0`. | `64M` |
+| `fast_field_cache` | Deprecated memory-capacity setting for the split-range cache, also accepted as `fast_field_cache_capacity`. Accepts a scalar capacity or a mapping with `memory_capacity` (alias `capacity`). Uses memory-only Feuer for all split ranges, including fast fields. Set to `0` to disable split-range caching. An explicit `disk_cache` and this setting are mutually exclusive. | `1G` |
+| `partial_request_cache` | Feuer cache for per-split partial responses to speed up subsequent requests. Accepts a memory capacity or a mapping with `memory_capacity` (alias `capacity`) and optional disk settings described below. Without disk settings, uses in-memory Feuer and needs no directory. Disable with `0`. Legacy alias: `partial_request_cache_capacity`. | `64M` |
+| `predicate_cache` | Feuer cache for predicate hit sets and known-absent terms. Accepts a memory capacity or a mapping with `memory_capacity` (alias `capacity`) and optional disk settings described below. Without disk settings, uses in-memory Feuer and needs no directory. Disable with `0`. Legacy alias: `predicate_cache_capacity`. | `256M` |
 | `max_num_concurrent_split_searches` | Maximum number of concurrent split search requests running on a Searcher. | `100` |
 | `split_cache` | Searcher split cache configuration options defined in the section below. Cache disabled if unspecified. | |
+| `disk_cache` | Process-wide Feuer cache for split footer and body byte ranges. Configuration options are defined below. Omitted or `null` uses the legacy memory capacity, defaulting to `1G` with no disk tier. | |
+| `disk_cache_directory` | Shared directory for Feuer cache files. Per-cache `path` overrides it. Setting this directory alone does not enable disk caching. | |
 | `request_timeout_secs` | The time before a search request is cancelled. This should match the timeout of the stack calling into quickwit if there is one set.  | `30` |
 | `use_metastore_read_replica` | If true, routes read-only metastore requests from searchers to nodes running the `metastore_read_replica` service. Searchers require at least one `metastore_read_replica` node at startup and do not fall back to the primary metastore. | `false` |
 
+Split footer and hotcache bytes use the same `disk_cache` memory and disk tiers as split body ranges. When `disk_cache` is disabled, opening a split fetches its footer from storage each time. Remove `split_footer_cache` and `split_footer_cache_capacity` from existing configurations. Both are rejected as unknown fields.
+
 ### Searcher split cache configuration
 
 This section contains the configuration options for the on-disk searcher split cache. Files are stored in the data directory under `searcher-split-cache/`.
@@ -328,19 +332,67 @@ This section contains the configuration options for the on-disk searcher split c
 | `max_num_splits` | Maximum number of splits allowed in the split cache.   | `10000` |
 | `num_concurrent_downloads` | Maximum number of concurrent download of splits. | `1` |
 
+### Searcher disk cache configuration
+
+This section configures Feuer's memory and disk cache of exact immutable split slices. Each `(full object URI, start, end)` is a versioned whole-object cache key, using the same Feuer API as the result caches. Only an identical byte range can hit. Covering or overlapping slices cannot serve other ranges, and entries are evicted whole. Cache misses for the same full object URI are batched for 1 ms. Pending reads with gaps of at most 1 MiB can share a download, up to a merged size of 8 MiB. Individual reads larger than 8 MiB remain supported but are not extended. Each caller's requested slice is cached separately. Downloaded gaps are not cached. Already-started downloads can serve covered requests but cannot be extended. Dropping the last waiting caller cancels the shared download.
+
+An explicit `disk_cache` mapping configures the split-range cache. If omitted or set to `null`, `fast_field_cache` (alias `fast_field_cache_capacity`) supplies its memory capacity, defaulting to `1G`, with no disk tier or directory required. A legacy capacity of `0` disables split-range caching. These deprecated names configure the same split-range cache; there is no separate fast-field cache. Setting both an explicit `disk_cache` mapping and a legacy capacity is an error, including a legacy capacity of `0`. `disk_cache: null` behaves exactly like omission and can be combined with a legacy capacity.
+
+| Property | Description | Default value |
+| --- | --- | --- |
+| `path` | Optional directory override for this cache. Defaults to `searcher.disk_cache_directory`. One of them must be set when `disk_capacity` is positive. Created if missing and must sit on a usable filesystem. Memory-only split-range caching requires no directory. Explicitly empty paths are rejected. | |
+| `disk_capacity` | Disk capacity budget, including metadata and alignment. Set to `0` to disable the disk tier and cache only in memory. Feuer handles alignment internally. The configured value need not be rounded. | |
+| `memory_capacity` | Positive, soft memory-tier eviction target, required even when `disk_capacity` is `0`. Oversized downloads and bytes retained by callers may exceed it. This is not a process memory limit. | |
+
+`partial_request_cache` and `predicate_cache` always use Feuer. Scalar capacities and mappings without disk settings use in-memory Feuer, with no directory required, even when a shared directory is configured. `memory_capacity` sets the memory budget (default `64M` and `256M`, respectively), with `capacity` and the legacy `*_cache_capacity` names accepted as backward-compatible aliases. A scalar `0` or a zero memory capacity without disk settings disables the cache. To add a disk tier, set `disk_capacity` and either `searcher.disk_cache_directory` or a per-cache `path` override. A per-cache `path` requires `disk_capacity`.
+
+The list-fields metadata cache also uses Feuer's memory tier. It remains an independent cache with the same memory capacity as `partial_request_cache`, including zero-capacity disabling. Result-cache disk settings do not enable a disk tier for list-fields metadata.
+
+Cache mappings serialize the RAM budget as `memory_capacity`. Both `memory_capacity` and `disk_capacity` serialize as integer byte counts to preserve exact budgets. Human-readable input such as `64MiB` is still accepted. Setting both `capacity` and `memory_capacity` in the same mapping is an error.
+
+For result caches with explicit `disk_capacity`, `memory_capacity` must be positive. A positive disk capacity also requires a nonempty resolved directory. `disk_capacity: 0` disables the disk tier and requires no directory. Explicitly empty directory settings are rejected. Result caches and `fast_field_cache` reject explicit `policy` and nonempty `virtual_caches` because Feuer owns eviction. The deprecated `fast_field_cache` mapping accepts a memory capacity only. Its `path` and `disk_capacity` settings remain unsupported. Use `disk_cache` to add a disk tier for split ranges, including fast-field reads.
+
+Feuer instances configured with disk settings share one `IoQueues` set, limiting total disk I/O concurrency. They are opened independently. Each instance has its own backing file and lock, disk budget, memory tier, buffer pool, eviction state, and background-write queue. They can share a directory because their fixed filenames are distinct:
+
+| Cache setting | Backing filename |
+| --- | --- |
+| `disk_cache` | `split_cache` |
+| `predicate_cache` | `predicate_cache` |
+| `partial_request_cache` | `partial_response_cache` |
+
+Lock files are named `.feuer.<filename>.lock`. Opening the same backing file twice fails. Initialization failures abort startup. All caches use Feuer's unified API. A disk capacity of `0` enables memory-only operation on every supported platform without disk I/O. Positive disk capacities require Linux.
+
+Result-cache keys include a format version and use the same stable serialized identity in both memory and disk. Split-cache keys use the `split-slice-v1` namespace. Memory-only result and list-fields caches work without a Tokio runtime. Memory-only cache capacities are soft eviction targets. Feuer can admit an entry larger than its shard's capacity after evicting other entries. Partial responses retain the same request normalization and cache-hit resource statistics as the previous RAM cache. Predicate disk reads through Tantivy's synchronous API run on CPU threads rather than Tokio workers.
+
+Feuer's native [metrics](../reference/metrics.md#feuer-cache-metrics) include a `cache` label (`split_range`, `partial_request`, `predicate`, or `list_fields`) to distinguish instances. Sum over this label to aggregate them. Memory-only caches expose Feuer's lookup, memory occupancy, and eviction metrics. Memory-only result and list-fields caches also retain Quickwit's cache hit/miss counters. Result-cache lookups use Feuer's lookup-only API, which reports misses separately from callback errors.
+
+Feuer's cost-aware scorer models a fixed source-request cost in equivalent transferred bytes. Quickwit sets this to `256000` for the split cache only. Predicate and partial-response caches retain Feuer's default of `0` (bytes-only scoring). The cost applies to both memory and disk tiers and is set per instance.
+
+Feuer owns cost-aware eviction and best-effort disk population. `FEUER_RECLAIM_SAMPLE_SIZE` is a positive integer (default `64`) limiting eviction candidates. `FEUER_ACCESS_COUNT_HALF_LIFE` controls demand decay, and `FEUER_IDLE_BUFFER_POOL_PERCENT` controls the idle buffer ceiling. These settings apply to memory-only caches as well as tiered caches. Invalid values cause cache initialization to fail.
+
+After the coalescer finalizes a download range, Quickwit acquires one aligned buffer from Feuer's pool and streams the response directly into it. Callers, the memory cache, and the disk-write queue share that allocation without a payload copy at handoff. Exact slices charge the full backing allocation capacity, including spare bucket capacity. Coalesced slices sharing an allocation each charge its full capacity, so accounting is conservative rather than deduplicated. The allocation becomes reusable after its last owner releases it, subject to Feuer's idle-pool capacity. The configured storage timeout/retry policy applies to the entire response body and retries reuse the destination buffer.
+
+Set `QW_FEUER_ACCESS_TRACE_URI` to an output prefix to export Feuer's native access traces using the node's storage configuration and credentials. Unset means disabled. An invalid or unwritable destination fails startup. Tracing can backpressure lookups, and packages are delivered at 8 MiB with no timed flush. See [Feuer access traces](../internals/feuer-access-trace.md) for the format and shutdown/completeness limitations.
 
 Example:
 
 ```yaml
 searcher:
   use_metastore_read_replica: false
-  fast_field_cache_capacity: 1G
-  split_footer_cache_capacity: 500M
-  partial_request_cache_capacity: 64M
   split_cache:
     max_num_bytes: 1G
     max_num_splits: 10000
     num_concurrent_downloads: 1
+  disk_cache_directory: /quickwit/qwdata/feuer-v1
+  disk_cache:
+    disk_capacity: 1500GiB
+    memory_capacity: 15GiB
+  partial_request_cache:
+    memory_capacity: 64MiB
+    disk_capacity: 20GiB
+  predicate_cache:
+    memory_capacity: 256MiB
+    disk_capacity: 100GiB
 ```
 
 ## Jaeger configuration

docs/deployment/cluster-sizing.md

@@ -58,10 +58,11 @@ Searcher nodes:
 - Provision more RAM if you expect many concurrent aggregation requests. By
   default, each request can use up to 500MB of RAM on each node.
 - Avoid instances with less than 4GB of RAM
-<!-- 1GB fast_field_cache_capacity + 0.5GB split_footer_cache_capacity + 0.5GB/req aggregation_memory_limit -->
-- Searcher nodes don't use disk unless the [split
-  cache](../configuration/node-config.md#Searcher-split-cache-configuration) is
-  explicitly enabled
+<!-- 1GB fast_field_cache_capacity + 0.5GB/req aggregation_memory_limit; configured disk_cache memory budgets are additional. -->
+- Searchers use disk when the [whole-split cache](../configuration/node-config.md#searcher-split-cache-configuration)
+  or a [Feuer disk tier](../configuration/node-config.md#searcher-disk-cache-configuration)
+  is explicitly enabled. Account for the independent memory and disk budgets of
+  the split-range, predicate, and partial-response caches.
 
 One strength of Quickwit is that its Searchers are stateless, which makes it
 easy to scale them up and down based on the workload. Scale the number of