Implementation Plan for HybridCache ReportTagMetrics

[mokarchi]

Overview

Fix #5989
The ReportTagMetrics feature in HybridCache enables emission of cache metrics with tag dimensions using System.Diagnostics.Metrics. This provides richer telemetry for cache performance analysis and debugging.

Configuration

Enable tag metrics reporting by setting the ReportTagMetrics option:

services.AddHybridCache(options =>
{
    options.ReportTagMetrics = true;
});

Metrics Emitted

When ReportTagMetrics is enabled, the following metrics are emitted with tag dimensions:

Metric Name	Description	Type
hybrid_cache.local.hits	Local cache hits	Counter
hybrid_cache.local.misses	Local cache misses	Counter
hybrid_cache.distributed.hits	Distributed cache hits	Counter
hybrid_cache.distributed.misses	Distributed cache misses	Counter
hybrid_cache.local.writes	Local cache writes	Counter
hybrid_cache.distributed.writes	Distributed cache writes	Counter
hybrid_cache.tag.invalidations	Tag invalidations	Counter

Usage Example

// Cache operations with tags
await cache.GetOrCreateAsync("user-profile", userId, 
    async (userId, token) => await GetUserProfileAsync(userId, token),
    tags: new[] { "region:us-west", "service:user-api", "environment:prod" });

// Tags will appear as metric dimensions when ReportTagMetrics = true

Integration with Observability Systems

OpenTelemetry

The metrics integrate seamlessly with OpenTelemetry:

builder.Services.AddOpenTelemetry()
    .WithMetrics(metrics =>
    {
        metrics.AddMeter("Microsoft.Extensions.Caching.Hybrid");
    });

Application Insights

Metrics are automatically collected when using Application Insights:

builder.Services.AddApplicationInsightsTelemetry();

Prometheus

Export metrics to Prometheus:

builder.Services.AddOpenTelemetry()
    .WithMetrics(metrics =>
    {
        metrics.AddMeter("Microsoft.Extensions.Caching.Hybrid")
               .AddPrometheusExporter();
    });

Backwards Compatibility

• The existing EventSource-based metrics continue to work unchanged
• ReportTagMetrics defaults to false, so no behavior changes unless explicitly enabled
• All existing telemetry consumers will continue to receive the same events

Microsoft Reviewers: Open in CodeFlow

[Copilot]

Pull Request Overview

This PR implements the ReportTagMetrics feature for HybridCache that enables emission of cache metrics with tag dimensions using System.Diagnostics.Metrics. The implementation allows for richer telemetry for cache performance analysis and debugging while maintaining backward compatibility.

Key changes include:

• Addition of System.Diagnostics.Metrics instruments with tag-aware capabilities to HybridCacheEventSource
• Integration of the ReportTagMetrics option throughout the cache implementation to conditionally emit tagged metrics
• Comprehensive test coverage for both the new functionality and backward compatibility

Reviewed Changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
HybridCacheEventSource.cs	Adds System.Diagnostics.Metrics instruments and methods for emitting tagged metrics
HybridCacheOptions.cs	Enhances documentation for ReportTagMetrics with security and PII guidance
DefaultHybridCache.cs	Integrates tagged metric reporting in cache hit/miss scenarios
DefaultHybridCache.TagInvalidation.cs	Adds tagged metrics for tag invalidation operations
DefaultHybridCache.StampedeStateT.cs	Integrates tagged metrics for distributed cache operations
DefaultHybridCache.L2.cs	Adds tagged metrics for local cache write operations
ReportTagMetricsTests.cs	Unit tests for the new tagged metrics functionality
ReportTagMetricsIntegrationTests.cs	Integration tests covering end-to-end tagged metrics scenarios
HybridCacheEventSourceTests.cs	Tests for EventSource methods with tag support
Microsoft.Extensions.Caching.Hybrid.Tests.csproj	Adds reference to diagnostics testing library

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[mokarchi]

@eerhardt Could you review this, please?

[mokarchi]

@eerhardt Could you review this, please?

@DeagleGross @jeffhandley @MihaZupan Could you review this, please?