Improved Redis caching article.

gfraiteur · gfraiteur · commit 3f2bae7c81b8 · 2025-09-01T13:30:03.000+02:00
diff --git a/conceptual/Caching/Backends/caching-redis.md b/conceptual/Caching/Backends/caching-redis.md
@@ -7,47 +7,70 @@ summary: "The document provides instructions on how to use Redis Cache with Post
 ---
 # Using Redis Cache
 
-[Redis](https://redis.io/) is a popular choice for distributed, in-memory caching.
+Our implementation uses the [StackExchange.Redis library](https://stackexchange.github.io/StackExchange.Redis/) internally. It is compatible with on-premises Redis Cache instances as well as with the [Azure Redis Cache](https://azure.microsoft.com/en-us/services/cache/) cloud service. We tested our adapter with single-node, master/replica, and sharded topologies.
+
+## Prerequisites
+
+In theory, this component should work with any Redis implementation supported by `StackExchange.Redis`.
+
+However, we only tested this component with the latest Redis version. Old versions or other implementations are not officially supported except on a ad-hoc basis for customers with an enterprise support plan.
+
+We performed tests with single-node, master/replica, and sharded cluster deployments.
 
-Our implementation uses [StackExchange.Redis library](https://stackexchange.github.io/StackExchange.Redis/) internally. It is compatible with on-premises Redis Cache instances as well as with the [Azure Redis Cache](https://azure.microsoft.com/en-us/services/cache/) cloud service. We tested our adapter with single-node, master/replica, and sharded topologies.
 
 ## Configuring the Redis server
 
-### To prepare your Redis server for use with PostSharp caching:
+To prepare your Redis server for use with PostSharp caching:
 
 1. Set up the eviction policy to `volatile-lru` or `volatile-random`. See https://redis.io/topics/lru-cache#eviction-policies for details.
 
     > [!CAUTION]
     > Other eviction policies than `volatile-lru` or `volatile-random` are not supported.
 
-    ```
-    maxmemory-policy volatile-lru
-    ```
 
-2. If you intend to enable events or use dependencies, configure keyspace notifications to include the `Exe` events. See https://redis.io/topics/notifications#configuration for details.
+2. If you intend to enable events or use dependencies, configure keyspace notifications to include the `Exe` events (_key event_ notifications for expirations and evictions). See https://redis.io/topics/notifications#configuration for details.
 
-    ```
-    notify-keyspace-events "Exe"
-    ```
+
+### Example
+
+`redis.conf`:
+
+```text
+maxmemory-policy volatile-lru
+notify-keyspace-events "Exe"
+```
 
 ## Configuring the caching backend in PostSharp
 
-### To set up PostSharp to use Redis for caching:
+To set up PostSharp to use Redis for caching:
 
 1. Add a reference to the [PostSharp.Patterns.Caching.Redis](https://www.nuget.org/packages/PostSharp.Patterns.Caching.Redis/) package.
 
 2. Create an instance of [StackExchange.Redis.ConnectionMultiplexer](https://stackexchange.github.io/StackExchange.Redis/Configuration).
 
 3. Create an instance of the <xref:PostSharp.Patterns.Caching.Backends.Redis.RedisCachingBackend> class using the <xref:PostSharp.Patterns.Caching.Backends.Redis.RedisCachingBackend.Create*> factory method and assign the instance to <xref:PostSharp.Patterns.Caching.CachingServices.DefaultBackend>, passing a <xref:PostSharp.Patterns.Caching.Backends.Redis.RedisCachingBackendConfiguration> object.
 
+4. Configure logging. See <xref:backends> to learn how to plug caching into your logging framework. <xref:PostSharp.Patterns.Caching.Backends.Redis.RedisCachingBackend> uses PostSharp Logging. While tuning performance, we recommend monitoring warnings.
+
 > [!IMPORTANT]
-> The caching backend has to be set before any cached method is called for the first time.
+> If one node enables the local cache, all nodes must enable events.
+
+In-memory cache must be enabled globally for the whole back-end. It is not possible to enable it at the level of individual classes or methods.
+> [!IMPORTANT]
+> The caching backend must be set before any cached method is called for the first time.
 
 ### Example
 
 ```csharp
+// Enable logging
+ oggingServices.DefaultBackend = new ConsoleLoggingBackend();
+LoggingServices.DefaultBackend.DefaultVerbosity.SetMinimalLevel( LogLevel.Warning, LoggingRoles.Caching );
+
+// Connect to Redis
 string connectionConfiguration = "localhost";
 ConnectionMultiplexer connection = ConnectionMultiplexer.Connect( connectionConfiguration );
+
+// Set Redis as the default backend.
 RedisCachingBackendConfiguration redisCachingConfiguration = new RedisCachingBackendConfiguration() { Prefix = "MyApp-1.0.1" };
 CachingServices.DefaultBackend = RedisCachingBackend.Create( connection, redisCachingConfiguration );
 ```
@@ -102,31 +125,10 @@ Garbage may therefore be due to three factors:
 - The <xref:PostSharp.Patterns.Caching.Backends.Redis.RedisCacheDependencyGarbageCollector> component was temporarily disabled because of high system load.
 - There was a race condition in setting a cache value (the version that loses becomes garbage).
 
-## Support for Redis clusters
-
- <xref:PostSharp.Patterns.Caching.Backends.Redis.RedisCachingBackend> has been tested in single-node, master/replica, and sharded cluster deployments.
-
 ## Resilience
 
  As with any part of a distributed system, <xref:PostSharp.Patterns.Caching.Backends.Redis.RedisCachingBackend> is a complex component that must be tuned and monitored with care.
 
-### Enabling logging
-
-<xref:PostSharp.Patterns.Caching.Backends.Redis.RedisCachingBackend> uses PostSharp Logging. While tuning performance, we recommend monitoring warnings.
-
-The following code shows how to enable logging for the caching component and redirect logging output to the console. See <xref:backends> to plug caching into your logging framework.
-
-```csharp
-ConsoleLoggingBackend loggingBackend = new();
-LoggingServices.DefaultBackend = loggingBackend;
-LoggingServices.DefaultBackend.DefaultVerbosity.SetMinimalLevel( LogLevel.Warning, LoggingRoles.Caching );
-```
-
-> [!IMPORTANT]
-> If one node enables the local cache, all nodes must enable events.
-
-In-memory cache must be enabled globally for the whole back-end. It is not possible to enable it at the level of individual classes or methods.
-
 ### Exception handling
 
 Failures are highly likely if your system is overloaded. Here is how they are handled:
@@ -148,28 +150,30 @@ If you expect high load, it is recommended to tune the following <xref:PostSharp
 The following <xref:PostSharp.Patterns.Caching.Backends.Redis.RedisCacheDependencyGarbageCollectorOptions> properties must also be properly tuned:
 
 - The <xref:PostSharp.Patterns.Caching.Backends.Redis.RedisCacheDependencyGarbageCollectorOptions.CacheCleanupDelay> property is the delay between the initialization of the component and the first cleanup, then between two subsequent cache cleanups, and defaults to 4 hours. Cleaning up the database too frequently is useless performance overhead, but doing it too late degrades performance even more. If the database contains too much garbage, Redis will start evicting _useful_ data, affecting your application performance. However it will never evict garbage. That's why you should increase the cache cleanup frequency if you see high memory usage or high levels of evictions.
-- The <xref:PostSharp.Patterns.Caching.Backends.Redis.RedisCacheDependencyGarbageCollectorOptions.CacheCleanupOptions.CacheCleanupOptions> property affects the cleanup process. It's important to keep the cleanup slow enough to avoid impacting your application's performance, but fast enough to finish before Redis runs out of memory. The <xref:PostSharp.Patterns.Caching.Implementation.CacheCleanupOptions.WaitDelay> is an artificial delay between processing each cache key, defaulting to 100 ms.
+- The <xref:PostSharp.Patterns.Caching.Backends.Redis.RedisCacheDependencyGarbageCollectorOptions.CacheCleanupOptions.CacheCleanupOptions> property affects the cleanup process. It is important to keep the cleanup slow enough to avoid impacting your application's performance, but fast enough to finish before Redis runs out of memory. The <xref:PostSharp.Patterns.Caching.Implementation.CacheCleanupOptions.WaitDelay> is an artificial delay between processing each cache key, defaulting to 100 ms.
 
-Note that you can run a manual cleanup by calling the <xref:PostSharp.Patterns.Caching.Implementation.CachingBackend.CleanUpAsync*?CachingBackend.CleanUpAsync> method. Do not run this method with the default options on a production database; these options are optimized for the cleanup operation's performance and may overload your server.
+Note that you can run a manual cleanup by calling the <xref:PostSharp.Patterns.Caching.Implementation.CachingBackend.CleanUpAsync*?CachingBackend.CleanUpAsync> method. Do not run this method with the default options on a production database; these options are optimized for cleanup performance and may overload your server.
 
 ### Monitoring
 
-The following metrics are relevant to assess the health of your caching set up:
+The following metrics are relevant for assessing the health of your caching setup:
 
-- Number of cache evictions per second. A high number might mean either insufficient caching memory, or ineffective caching strategy - caching things that are not worth it (too many cache misses)
-- Number of cache expirations per second. A high number might mean too small expiration delays
-- Number of warnings per minute in the caching component. A high number means that your system is overloaded.
+- Number of cache evictions per second. A high number might indicate either insufficient caching memory or an ineffective caching strategy—caching things that are not worth it (too many cache misses)
+- Number of cache expirations per second. A high number might indicate too-short expiration delays
+- Number of warnings per minute in the caching component. A high number indicates that your system is overloaded.
 
 If you want to gather statistics about cache hits and misses, you can do so by implementing a <xref:PostSharp.Patterns.Caching.Implementation.CachingBackendEnhancer> that overrides the <xref:PostSharp.Patterns.Caching.Implementation.CachingBackend.GetItemCore*> and <xref:PostSharp.Patterns.Caching.Implementation.CachingBackend.GetItemAsyncCore*> methods (a `null` return value means a cache miss).
 
-## Data schema
+## Data schema and complexity analysis
+
+### Data schema
 
 When dependencies are enabled, <xref:PostSharp.Patterns.Caching.Backends.Redis.RedisCachingBackend> relies on these keys:
 
 1. Item version: `<prefix>:<schema-version>:{<item-key>}:ver` — unique string identifier.
 2. Item value: `<prefix>:<schema-version>:{<item-key>}:val:<item-version>` — a list with values: `[<item-value>, <item-sliding-expiration>, <tag0>, <tag1> ... <tagn>]`.
-3. Backward dependencies: `<prefix>:<schema-version>:{<dependency-key>}:bdep` — hash set of `<item-version>:<item-key>`.
-4. Forward dependencies: `<prefix>:<schema-version>:{<item-key>}:fdep:<item-version>` — list of `<dependency-key>`.
+3. Forward dependencies: `<prefix>:<schema-version>:{<item-key>}:fdep:<item-version>` — list of `<dependency-key>`.
+4. Backward dependencies: `<prefix>:<schema-version>:{<dependency-key>}:bdep` — hash set of `<item-version>:<item-key>`.
 
 When dependencies are disabled, only the item value record is used.
 
@@ -182,10 +186,84 @@ In this description, elements between angle brackets are placeholders and mean t
 - `<item-version>` is a randomly generated item version.
 - `<dependency-key>` is either a dependency key or a cache item key, when the cache item is itself a dependency (recursive dependencies), where `{`, `}` and `:` have been escaped.
 
-## Clearing the cache
+### Big O analysis
+
+In the following analysis, we use the following parameters:
+- `Items` is the number of items.
+- `Dependencies` is the number of dependencies and items (as items can act as dependencies if a cached method calls another cached method).
+- `KeySize` is the average size of item or dependency keys (after compression, if enabled).
+- `ValueSize` is the average size of item values (i.e. the serialized data).
+- `Dependencies_Per_Item` is the average number of dependencies per item (first level, not recursive).
+- `Items_Per_Dependency` is the average number of items that a dependency or another item depends on (first level, not recursive).
+- `Recursive_Items_Per_Dependency` is the average number of items that a dependency or another item depends on, recursively.
+
+Memory usage is the sum of:
+
+- Version: `O(Items * KeySize)`
+- Value: `O(Items * (KeySize + ValueSize))`
+- Forward dependencies: `O(Items * KeySize * (1 + Dependencies_Per_Item))`
+- Backward dependencies: `O((Dependencies + Items) * KeySize * Items_Per_Dependency)`
+
+Time complexity of operations is the following:
+
+- Get: `O(1)`
+- Set: `O(Dependencies_Per_Item * (1 + Recursive_Items_Per_Dependency))`
+- Invalidate: `O(Recursive_Items_Per_Dependency * Dependencies_Per_Item)`
+
+Race conditions affecting performance can happen when several operations attempt to set the same key. In this case, Redis transactions are used to achieve consistency, and they might be repeated in case of race. Adding items that share the same dependencies do not cause races and do not affect performance.
+
+### Clearing the cache
 
 To remove all cache keys, you can:
 
 * Use the `FLUSHDB` Redis command to delete all keys in the selected database, even those that don’t match the prefix.
 * Use the `SCAN <prefix>:*` command to identify all keys, then use `DEL` for each key.
 * Use the <xref:PostSharp.Patterns.Caching.Implementation.CachingBackend.ClearAsync*> method, which does a `SCAN <prefix>:<schema-version>:*` command, then `UNLINK` for each key.
+
+## Troubleshooting
+
+### Observing the cache
+
+- Make sure that `LoggingServices.DefaultBackend` has been properly configured so that the logging messages generated by <xref:PostSharp.Patterns.Caching.Backends.Redis.RedisCachingBackend> are routed to a service where you can monitor them.
+
+- If necessary, increase the logging verbosity to `Info` (suitable for production in troubleshooting situations) or `Debug` (extremely verbose and never suitable for production). If you don't see any message in `Debug` verbosity it means that logging is not properly configured.
+
+    ```
+    LoggingServices.DefaultBackend.DefaultVerbosity.SetMinimalLevel( LogLevel.Info, LoggingRoles.Caching );
+    ```
+
+- Use the Redis `MONITOR` command in Redis CLI, or Redis Insight's profiler tool.
+
+- Use the Redis `SUBSCRIBE _keyevents@0__*` command in Redis CLI, or use Redis Insight's Pub/Sub tool and subscribe to the pattern `_keyevents@0__*`.
+
+### Common issues
+
+- **Problem: Cache accesses never hit, always miss.**
+
+    Cause: <xref:PostSharp.Patterns.Caching.Backends.Redis.RedisCachingBackend> cannot connect to Redis and the `AbortOnConnect` option is set to `false`. You should see errors in your logs. If you don't, logging is not properly configured.
+
+    Remedy: Check that you can connect to the Redis server, for instance using `connection.GetDatabase.Ping()`.
+
+- **Problem: the collector component reports dozens of errors per minute.**
+
+    Cause: the collector is overloaded because of excessive evictions and expirations.
+
+    Remedies:
+
+    - If expirations are excessive, increase the cache item expiry delay.
+    - If evictions are excessive, remove caching from methods with a high miss ratio.
+    - If the problem is intermittent, tune the <xref:PostSharp.Patterns.Caching.Backends.Redis.RedisCachingBackendConfiguration.BackgroundTasksMaxConcurrency> and <xref:PostSharp.Patterns.Caching.Backends.Redis.RedisCachingBackendConfiguration.BackgroundTasksOverloadedThreshold>
+
+- **Problem: InvalidCacheItemException or InvalidCastException are logged after an application upgrade.**
+
+    Cause: the serialization of new and old data classes is not compatible with each other, but the two versions of the application use the same <xref:PostSharp.Patterns.Caching.Backends.Redis.RedisCachingBackendConfiguration.Prefix> and <xref:PostSharp.Patterns.Caching.Backends.Redis.RedisCachingBackendConfiguration.Database> properties.
+
+    Remedies:
+
+    - Use a different value of the <xref:PostSharp.Patterns.Caching.Backends.Redis.RedisCachingBackendConfiguration.Prefix> or <xref:PostSharp.Patterns.Caching.Backends.Redis.RedisCachingBackendConfiguration.Database> property when you update cached classes.
+    - Use a serializer that makes the data contract explicit, i.e. <xref:PostSharp.Patterns.Caching.Serializers.DataContractSerializer> or <xref:PostSharp.Patterns.Caching.Serializers.JsonCachingSerializer> instead of <xref:PostSharp.Patterns.Caching.Serializers.BinarySerializer> or <xref:PostSharp.Patterns.Caching.Serializers.PortableSerializer> -- and maintain serialization compatibility when you update the classes.
+
+## See also
+
+- [StackExchange.Redis documentation](https://stackexchange.github.io/StackExchange.Redis/)
+- [Redis Insight](https://redis.io/insight/) for monitoring during development
