Stat caching in Cloud Storage FUSE

This document provides details on stat caching in Cloud Storage FUSE, which accelerates file metadata operations for applications that frequently check file attributes. Frequent file attribution checks are common for many applications that repeatedly check if a file has changed. Stat caching helps reduce the number of GetMetadata calls for Cloud Storage.

Benefits of stat caching

• Improved performance for file attribute operations: stat caching stores object metadata such as file size, modification time, permissions, and other standard file attributes. Enabling stat caching significantly speeds up operations that query these attributes because Cloud Storage can often retrieve this information from the local cache.

• Reduced latency: By serving metadata from the local stat cache, Cloud Storage FUSE avoids network round trips to Cloud Storage for a stat object request, lowering latency of metadata-heavy operations.

• Negative stat caching: you can cache information about non-existent files or directories, meaning if an application frequently checks for a file that isn't there, the negative result can be cached for a short time to live (TTL), preventing repeated lookups to Cloud Storage for the same non-existent path.

Configure stat caching

The stat cache is enabled by default. Configure it by using the gcsfuse command.

To set the maximum size of the cache, provide a value for one of the following:

• gcsfuse option: --stat-cache-max-size-mb
• Configuration file field: metadata-cache:stat-cache-max-size-mb

Note: This property is a mount-level limit, and actual memory usage might be lower than the value you specify. Alternatively, you can set the property to a value of -1 to let the stat cache use as much memory as needed.

For more information about default and recommended values for configuring the stat cache, see the Cloud Storage FUSE CLI reference and Cloud Storage FUSE configuration file pages.

Configure negative stat caching

Cloud Storage FUSE also offers a negative stat caching capability, which lets you set a TTL for stat cache entries for non-existent files, or negative results. The TTL of the negative stat cache is controlled using one the following methods:

• gcsfuse option: --metadata-cache-negative-ttl-secs
• Configuration file field: metadata-cache:negative-ttl-secs

To learn more about stat caching, see Cloud Storage FUSE semantics in the Cloud Storage FUSE GitHub documentation.

What's next

• Review considerations for caching in Cloud Storage FUSE.

• Read more about how to improve performance.