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