Stat caching in Cloud Storage FUSE accelerates file metadata operations for
applications that frequently check file attributes, such as applications that
repeatedly check whether a file has changed. By caching file metadata, stat
caching helps reduce the number of `GetMetadata` calls to 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`](https://docs.cloud.google.com/storage/docs/cloud-storage-fuse/cli-options.md.txt#stat-cache-max-size-mb)
- Configuration file field: [`metadata-cache:stat-cache-max-size-mb`](https://docs.cloud.google.com/storage/docs/cloud-storage-fuse/config-file.md.txt#stat-cache-max-size-mb)

> [!NOTE]
> **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](https://docs.cloud.google.com/storage/docs/cloud-storage-fuse/cli-options.md.txt#stat-cache-max-size-mb) and
[Cloud Storage FUSE configuration file](https://docs.cloud.google.com/storage/docs/cloud-storage-fuse/config-file.md.txt#stat-cache-max-size-mb) 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`](https://docs.cloud.google.com/storage/docs/cloud-storage-fuse/cli-options.md.txt#metadata-cache-negative-ttl-secs)
- Configuration file field: [`metadata-cache:negative-ttl-secs`](https://docs.cloud.google.com/storage/docs/cloud-storage-fuse/config-file.md.txt#negative-ttl-secs)

To learn more about stat caching, see
[Cloud Storage FUSE semantics](https://github.com/GoogleCloudPlatform/gcsfuse/blob/master/docs/semantics.md#caching) in the Cloud Storage FUSE GitHub documentation.

## What's next

- Review [considerations for caching in Cloud Storage FUSE](https://docs.cloud.google.com/storage/docs/cloud-storage-fuse/caching.md.txt#considerations).

- Read more about [how to improve performance](https://docs.cloud.google.com/storage/docs/cloud-storage-fuse/performance.md.txt).