Implementation Plan for HybridCache ReportTagMetrics

src/Libraries/Microsoft.Extensions.Caching.Hybrid/HybridCacheOptions.cs

@@ -53,8 +53,37 @@ public class HybridCacheOptions
     /// <see langword="true"/> to use "tags" data as dimensions on metric reporting; otherwise, <see langword="false"/>.
     /// </value>
     /// <remarks>
-    /// If enabled, take care to ensure that tags don't contain data that
-    /// should not be visible in metrics systems.
+    /// <para>
+    /// When enabled, cache operations will emit System.Diagnostics.Metrics with tag values as dimensions,
+    /// providing richer telemetry for cache performance analysis by tag categories.
+    /// </para>
+    /// <para>
+    /// <strong>Important PII and Security Considerations:</strong>
+    /// </para>
+    /// <list type="bullet">
+    /// <item><description>
+    /// Ensure that tag values do not contain personally identifiable information (PII), 
+    /// sensitive data, or high-cardinality values that could overwhelm metrics systems.
+    /// </description></item>
+    /// <item><description>
+    /// Tag values will be visible in metrics collection systems, dashboards, and telemetry pipelines.
+    /// Only use tags that are safe for observability purposes.
+    /// </description></item>
+    /// <item><description>
+    /// Consider using categorical values like "region", "service", "environment" rather than 
+    /// user-specific identifiers or sensitive business data.
+    /// </description></item>
+    /// <item><description>
+    /// High-cardinality tags (e.g., user IDs, session IDs) can cause performance issues 
+    /// in metrics systems and should be avoided.
+    /// </description></item>
+    /// </list>
+    /// <para>
+    /// Example of appropriate tags: ["region:us-west", "service:api", "environment:prod"].
+    /// </para>
+    /// <para>
+    /// Example of inappropriate tags: ["user:[email protected]", "session:abc123", "customer-data:sensitive"].
+    /// </para>
     /// </remarks>
     public bool ReportTagMetrics { get; set; }
 

src/Libraries/Microsoft.Extensions.Caching.Hybrid/Internal/DefaultHybridCache.L2.cs

@@ -211,9 +211,9 @@ internal void SetL1<T>(string key, CacheItem<T> value, HybridCacheEntryOptions?
             // commit
             cacheEntry.Dispose();
 
-            if (HybridCacheEventSource.Log.IsEnabled())
+            if (HybridCacheEventSource.Log.IsEnabled() || _options.ReportTagMetrics)
             {
-                HybridCacheEventSource.Log.LocalCacheWrite();
+                HybridCacheEventSource.Log.LocalCacheWriteWithTags(value.Tags, _options.ReportTagMetrics);
             }
         }
     }

src/Libraries/Microsoft.Extensions.Caching.Hybrid/Internal/DefaultHybridCache.StampedeStateT.cs

@@ -5,11 +5,9 @@
 using System.Buffers;
 using System.Diagnostics;
 using System.Diagnostics.CodeAnalysis;
-using System.Text;
 using System.Threading;
 using System.Threading.Tasks;
 using Microsoft.Extensions.Logging;
-using static Microsoft.Extensions.Caching.Hybrid.Internal.DefaultHybridCache;
 
 namespace Microsoft.Extensions.Caching.Hybrid.Internal;
 
@@ -188,15 +186,15 @@ private async Task BackgroundFetchAsync()
                         }
 
                         result = await Cache.GetFromL2DirectAsync(Key.Key, SharedToken).ConfigureAwait(false);
-                        if (eventSourceEnabled)
+                        if (eventSourceEnabled || Cache._options.ReportTagMetrics)
                         {
                             if (result.HasValue)
                             {
-                                HybridCacheEventSource.Log.DistributedCacheHit();
+                                HybridCacheEventSource.Log.DistributedCacheHitWithTags(CacheItem.Tags, Cache._options.ReportTagMetrics);
                             }
                             else
                             {
-                                HybridCacheEventSource.Log.DistributedCacheMiss();
+                                HybridCacheEventSource.Log.DistributedCacheMissWithTags(CacheItem.Tags, Cache._options.ReportTagMetrics);
                             }
                         }
                     }
@@ -367,9 +365,9 @@ private async Task BackgroundFetchAsync()
                                 {
                                     await Cache.SetL2Async(Key.Key, cacheItem, in buffer, _options, SharedToken).ConfigureAwait(false);
 
-                                    if (eventSourceEnabled)
+                                    if (eventSourceEnabled || Cache._options.ReportTagMetrics)
                                     {
-                                        HybridCacheEventSource.Log.DistributedCacheWrite();
+                                        HybridCacheEventSource.Log.DistributedCacheWriteWithTags(CacheItem.Tags, Cache._options.ReportTagMetrics);
                                     }
                                 }
                                 catch (Exception ex)

src/Libraries/Microsoft.Extensions.Caching.Hybrid/Internal/DefaultHybridCache.TagInvalidation.cs

@@ -254,9 +254,9 @@ private void InvalidateTagLocalCore(string tag, long timestamp, bool isNow)
         {
             _tagInvalidationTimes[tag] = timestampTask;
 
-            if (HybridCacheEventSource.Log.IsEnabled())
+            if (HybridCacheEventSource.Log.IsEnabled() || _options.ReportTagMetrics)
             {
-                HybridCacheEventSource.Log.TagInvalidated();
+                HybridCacheEventSource.Log.TagInvalidatedWithTags(tag, _options.ReportTagMetrics);
             }
         }
     }

src/Libraries/Microsoft.Extensions.Caching.Hybrid/Internal/DefaultHybridCache.cs

@@ -152,25 +152,26 @@ public override ValueTask<T> GetOrCreateAsync<TState, T>(string key, TState stat
         }
 
         bool eventSourceEnabled = HybridCacheEventSource.Log.IsEnabled();
+        TagSet tagSet = TagSet.Create(tags);
 
         if ((flags & HybridCacheEntryFlags.DisableLocalCacheRead) == 0)
         {
             if (TryGetExisting<T>(key, out CacheItem<T>? typed)
                 && typed.TryGetValue(_logger, out T? value))
             {
                 // short-circuit
-                if (eventSourceEnabled)
+                if (eventSourceEnabled || _options.ReportTagMetrics)
                 {
-                    HybridCacheEventSource.Log.LocalCacheHit();
+                    HybridCacheEventSource.Log.LocalCacheHitWithTags(tagSet, _options.ReportTagMetrics);
                 }
 
                 return new(value);
             }
             else
             {
-                if (eventSourceEnabled)
+                if (eventSourceEnabled || _options.ReportTagMetrics)
                 {
-                    HybridCacheEventSource.Log.LocalCacheMiss();
+                    HybridCacheEventSource.Log.LocalCacheMissWithTags(tagSet, _options.ReportTagMetrics);
                 }
             }
         }