feat(.NET): Caches Module (#10266)

Author: bitsandfoxes

docs/platforms/dotnet/common/performance/instrumentation/custom-instrumentation/caches-module.mdx

@@ -0,0 +1,105 @@
+---
+title: Instrument Caches
+sidebar_order: 1000
+description: "Learn how to manually instrument your code to use Sentry's Caches module. "
+---
+
+A cache can be used to speed up data retrieval, thereby improving application performance. Because instead of getting data from a potentially slow data layer, your application will be getting data from memory (in a best case scenario). Caching can speed up read-heavy workloads for applications like Q&A portals, gaming, media sharing, and social networking.
+
+Sentry offers a [cache-monitoring dashboard](https://sentry.io/orgredirect/organizations/:orgslug/insights/caches/) for getting an overview of your application's caches.
+
+To make it possible for Sentry to give you an overview of your cache performance, you'll need to create two spans - one indicating that something is being put into the cache, and a second one indicating that something is being fetched from the cache.
+
+Make sure that there's a transaction running when you create the spans. If you're using a web framework like ASP.NET Core those transactions will be created for you automatically. See <PlatformLink to='/performance/'>Performance Monitoring</PlatformLink> for more information.
+
+For detailed information about which data can be set, see the [Cache Module Developer Specification](https://develop.sentry.dev/sdk/performance/modules/caches/).
+
+## Manual Instrumentation
+
+Follow the steps below to make sure your Cache related spans end up in Sentry correctly.
+
+### Add Span When Putting Data Into the Cache
+
+1. Set the cache value with whatever cache library you happen to be using.
+2. Wrap the part of your application that uses the cached value with  `Sentry.with_child_span { |span| ... }`
+3. Set `op` to `cache.put`.
+4. Set `cache.item_size` to an integer representing the size of the cached item.
+
+### Add Span When Retrieving Data From the Cache
+
+1. Fetch the cached value from whatever cache library you happen to be using.
+2. Wrap the part of your application that uses the cached value with  `Sentry.with_child_span { |span| ... }`
+3. Set `op` to `cache.get`.
+4. Set `cache.hit` to a boolean value representing whether the value was successfully fetched from the cache or not.
+5. Set `cache.item_size` to an integer representing the size of the cached item.
+
+### Example
+
+Consider the following example service using `IMemoryCache` allowing you to `SetInCache` and `GetFromCache`.
+
+```csharp
+using Microsoft.Extensions.Caching.Memory;
+
+public class MyCachingService
+{
+    private readonly IMemoryCache _cache;
+
+    public MyCachingService(IMemoryCache cache)
+    {
+        _cache = cache;
+    }
+
+    public void SetInCache(string cacheKey, object value)
+    {
+        var cacheSpan = SentrySdk.GetSpan()?.StartChild("cache.put");
+
+        // Describe the cache server you are accessing
+        cacheSpan?.SetExtra("network.peer.address", "cache.example.com/supercache");
+        cacheSpan?.SetExtra("network.peer.port", 9000);
+
+        // Set the key you're going to use to add to the cache
+        cacheSpan?.SetExtra("cache.key", cacheKey);
+
+        // Optional: You can also provide the cached item's size
+        // cacheSpan?.SetExtra("cache.item_size", /* item size in bytes */);
+
+        // Add an item to your cache
+        _cache.Set(cacheKey, value);
+
+        cacheSpan?.Finish();
+    }
+
+    public object? GetFromCache(string cacheKey)
+    {
+        var cacheSpan = SentrySdk.GetSpan()?.StartChild("cache.get");
+
+        // Describe the cache server you are accessing
+        cacheSpan?.SetExtra("network.peer.address", "cache.example.com/supercache");
+        cacheSpan?.SetExtra("network.peer.port", 9000);
+
+        // Set the key you're going to use to retrieve from the cache
+        cacheSpan?.SetExtra("cache.key", cacheKey);
+
+        // Attempt to retrieve the cached item
+        if (_cache.TryGetValue(cacheKey, out var cachedValue))
+        {
+            // If you retrieved a value, the cache was hit
+            cacheSpan?.SetExtra("cache.hit", true);
+
+            // Optional: You can also provide the cached item's size
+            // cacheSpan.SetExtra("cache.item_size", /* item size in bytes */);
+
+            cacheSpan?.Finish();
+
+            return cachedValue;
+        }
+
+        // If you could not retrieve a value, it was a miss
+        cacheSpan?.SetExtra("cache.hit", false);
+        cacheSpan?.Finish();
+        return null;
+    }
+}
+```
+
+You should now have the right spans in place. Head over to the [Cache dashboard](https://sentry.io/orgredirect/organizations/:orgslug/performance/caches/) to see how your cache is performing.