Redis: improvements

Author: gfraiteur

conceptual/Caching/Backends/caching-redis.md

@@ -127,7 +127,7 @@ LoggingServices.DefaultBackend.DefaultVerbosity.SetMinimalLevel( LogLevel.Warnin
 
 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
+### Exception handling
 
 Failures are highly likely if your system is overloaded. Here is how they are handled:
 
@@ -136,7 +136,7 @@ Failures are highly likely if your system is overloaded. Here is how they are ha
 
 The exception handling policy described above is abstracted by the <xref:PostSharp.Patterns.Caching.Resilience.IExceptionHandlingPolicy> interface and configured by the <xref:PostSharp.Patterns.Caching.Backends.Redis.RedisCachingBackendConfiguration.ExceptionHandlingPolicy> property.
 
-## Performance tuning
+### Performance tuning
 
 With any level of load, it is recommended to enable cache key compression by assigning the <xref:PostSharp.Patterns.Caching.CachingServices.DefaultKeyBuilder?CachingServices.DefaultKeyBuilder> property to a <xref:PostSharp.Patterns.Caching.Implementation.CacheKeyBuilder> instance with a non-default <xref:PostSharp.Patterns.Caching.Implementation.CacheKeyHashingAlgorithm>.
 
@@ -152,31 +152,40 @@ The following <xref:PostSharp.Patterns.Caching.Backends.Redis.RedisCacheDependen
 
 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.
 
+### Monitoring
+
+The following metrics are relevant to assess the health of your caching set up:
+
+- 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.
+
+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
 
 When dependencies are enabled, <xref:PostSharp.Patterns.Caching.Backends.Redis.RedisCachingBackend> relies on these keys:
 
-1. Item version: `<prefix>:<schema-version>:val:<hash>:<item-version>:<item-key>` — string.
-2. Item value: `<prefix>:<schema-version>:ver:<hash>:<item-key>` — a list with values: `[<item-value>, <item-sliding-expiration>, <tag0>, <tag1> ... <tagn>]`.
-3. Backward dependencies: `<prefix>:<schema-version>:bdep:<hash>:<dependency-key>` — hash set of `<item-version>:<item-key>`.
-4. Forward dependencies: `<prefix>:<schema-version>:fdep:<hash>:<item-version>:<item-key>` — list of `<item-key>`.
+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>`.
 
 When dependencies are disabled, only the item value record is used.
 
 In this description, elements between angle brackets are placeholders and mean the following:
 
-- `<item-key>` is the cache key (as generated by <xref:PostSharp.Patterns.Caching.Implementation.CacheKeyBuilder>), where `{` and `}` are escaped.
+- `<item-key>` is the cache key (as generated by <xref:PostSharp.Patterns.Caching.Implementation.CacheKeyBuilder>), where `{`, `}` and `:` have been escaped.
 - `<item-value>` is the serialized cache value.
 - `<prefix>` is the value of the <xref:PostSharp.Patterns.Caching.Backends.Redis.RedisCachingBackendConfiguration.Prefix> property.
 - `<schema-version>` is the version of the data schema internal to <xref:PostSharp.Patterns.Caching.Backends.Redis.RedisCachingBackend>.
-- `<hash>` is a 16-bit hash of `<item-key>` surrounded with curly brackets, e.g. `{Aj4}`, unless the <xref:PostSharp.Patterns.Caching.Backends.Redis.RedisCachingBackendConfiguration.Prefix> property already contains a sharding hash (which is not recommended). This hash ensures that all keys corresponding to the same cache item reside in the same Redis node.
 - `<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 `}` are escaped.
+- `<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
 
 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 `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.