You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Starting with version 6.0, Redis provides [Client-Side Caching](https://redis.io/docs/latest/develop/reference/client-side-caching) which allows clients to maintain local caches of data in a faster and more efficient way. JuiceFS includes full support for this feature, offering significant performance improvements for metadata operations.
4
+
5
+
## How it works
6
+
7
+
Redis Client-Side Caching (CSC) works by:
8
+
9
+
1. The client enables tracking mode with `CLIENT TRACKING ON BCAST`
10
+
2. The client caches data locally after reading it from Redis
11
+
3. Redis notifies the client when cached keys are modified by any client
12
+
4. The client invalidates those keys in its local cache
13
+
14
+
This results in reduced network traffic, lower latency, and higher throughput.
15
+
16
+
## Configuration
17
+
18
+
JuiceFS supports Redis CSC through the following options in the metadata URL:
--meta-url="redis://localhost/1?client-cache=true&client-cache-size=500"# Set cache size (default 12800)
23
+
--meta-url="redis://localhost/1?client-cache=true&client-cache-expire=60s"# Set cache expiration (default: 60s)
24
+
```
25
+
26
+
### Options
27
+
28
+
-`client-cache`: Enables client-side caching in BCAST mode (set to any value except "false")
29
+
-`client-cache-size`: Maximum cache size (default: 12800)
30
+
-`client-cache-expire`: Cache expiration time (default: 60s)
31
+
-`client-cache-preload`: Number of file objects under the root directory preloaded after mounting. (default: 0)
32
+
33
+
When client-side caching is enabled, JuiceFS caches:
34
+
35
+
1.**Inode attributes**: File/directory metadata like permissions, size, timestamps
36
+
2.**Directory entries**: Name to inode mappings for faster lookups
37
+
38
+
> **Note:** Redis Client Side Cache requires Redis server version 6.0 or higher. Using this feature with older Redis versions will result in errors.
39
+
40
+
### Preloading Cache
41
+
42
+
When client-side caching is enabled and `client-cache-preload` is set, JuiceFS will preload the file-object attributes and entries under the root directory after mounting. This lazy preloading happens in the background and helps to:
43
+
44
+
1. Warm up the cache for common operations
45
+
2. Reduce latency for initial file system operations
46
+
3. Provide better performance from the moment the file system is mounted
47
+
48
+
The preloading process intelligently prioritizes the most important inodes by:
49
+
50
+
1. Starting with the root directory
51
+
2. Loading the most frequently accessed top-level directories and files
52
+
3. Recursively exploring important subdirectories
53
+
54
+
The preloading process runs in a background goroutine with fail-safe mechanisms and won't block or affect normal file system operations.
55
+
56
+
## Modes
57
+
58
+
JuiceFS uses BCAST mode for simplicity and reliability:
59
+
60
+
-**BCAST mode**: All keys accessed by the client are tracked and notifications are sent for any changes.
61
+
62
+
BCAST mode provides the simplest implementation while ensuring cache coherence across all clients.
63
+
64
+
## Requirements
65
+
66
+
- Redis server version 6.0 or higher
67
+
- JuiceFS with CSC support enabled
68
+
69
+
## Performance Considerations
70
+
71
+
1. The default 12800 cache size should be sufficient for most workloads
72
+
2. For very large filesystems with millions of files, you may benefit from increasing the cache size
73
+
3. The cache is most effective for metadata-heavy workloads with many repeated operations
74
+
4. For very write-heavy workloads, consider disabling CSC as invalidation traffic may offset benefits
75
+
76
+
## Troubleshooting
77
+
78
+
If you experience crashes or instability with CSC enabled:
79
+
80
+
1. Update to the latest JuiceFS version which contains important fixes for CSC
81
+
2. Try reducing the cache size with `client-cache-size`
82
+
3. Check Redis server logs for any memory or client tracking issues
83
+
4. Make sure your Redis server version is 6.0 or higher
84
+
5. If problems persist, disable CSC by removing the `client-cache` parameter
85
+
86
+
JuiceFS includes robust error handling for various Redis CSC-specific responses to ensure stable operation even when Redis sends unexpected response formats due to client tracking.
0 commit comments