Asynchronous Metadata Prefetching: Accelerate Metadata-Heavy Workloads

In this release, we are introducing an intelligent directory-aware asynchronous metadata prefetch mechanism designed to significantly reduce latency for file lookups by proactively populating the metadata cache. This feature also addresses performance degradation caused by cache evictions in large buckets by automatically "self-healing" the metadata cache when entries are missing or expired.

By fetching directory metadata in batches in the background, this feature can save approximately 20ms per file access and improve overall performance by up to 48% for metadata-intensive workloads like small file reads. Additionally, it offers massive cost efficiency by reducing GCS API calls (e.g., from 10,000 individual lookups to just 2 List calls for a 5,000-file directory), potentially lowering metadata access costs by over 90%.

• Feature Enablement: This feature is disabled by default in this release and can be enabled with the --enable-metadata-prefetch flag or metadata-cache:enable-metadata-prefetch config.
• Use Cases: Metadata-heavy workloads such as large-scale data processing with many small files and any scenarios where high directory locality is expected. Sample use cases include vision model building with many small image files or language models that work on crawled web data or Electronic Design Automation(EDA) simulation.
• Memory Usage: Memory consumption is bounded by the existing stat-cache-max-size-mb configuration (default: 34 MiB). Prefetch batches are limited to 5,000 entries (configurable) per directory to minimize memory/CPU pressure.
• CPU Usage: CPU consumption is typically lower when enabled due to the significant reduction in metadata network calls. Concurrent prefetch activity is strictly throttled by a global concurrency limit (10 by default; configurable) to prevent resource exhaustion.
• Large Directory Optimization: For directories with more than 5000 files, the system automatically switches to a Targeted Mode. Instead of fetching the entire directory, it only caches the immediate lexicographical siblings(up to 5K) of the accessed file, ensuring efficient scaling without excessive resource usage.

New Configuration Flags

The following flags can be used to configure this feature within the metadata-cache section of your configuration or as command-line arguments:

• enable-metadata-prefetch (bool)
  Enables background prefetching of metadata for objects within a directory during a cache miss. This feature performs a batch update to the metadata cache, significantly reducing latency for subsequent lookups of files in the directory.
  Default: False
• metadata-prefetch-entries-limit (Int)
  The maximum number of metadata entries (files and directories) to prefetch into the cache upon a prefetch trigger. Note that values higher than 5000 will trigger multiple sequential GCS List calls per directory, as a single call is capped at 5000 results.
  Default: 5000
• Metadata-prefetch-max-workers (Int)
  The maximum number of concurrent background workers allowed to perform metadata prefetching across all directories. Each directory is limited to one active worker at a time.
  Default: 10

Type cache deprecation

Starting with version 3.8.0, type cache is deprecated. Metadata cache will take care of serving type information (i.e, where it's a file or directory) now. All type-cache related flags such as enable-nonexistent-type-cache and type-cache-max-size-mb, are now no-op.

Reduced GCS Egress for Random Reads

Optimized initial read handling to reduce the initial egress. Previously, all initial requests were treated as sequential, triggering 200MB read requests. Now, initial requests with non-zero offsets are treated as random, utilizing a 1MB read requests.

Bug Fixes and Improvements

• A4X-Max has been added as a high-performance machine type.
• Histogram representations for metrics have been adjusted to focus on high latency cases by adjusting histogram boundaries. For eg, fs-op latencies more than 100ms would get adjusted in histogram to have more details than previous representation that truncates them.