Add built-in OpenTelemetry metrics to MemoryCache

[rjmurillo]

Summary

Adds OpenTelemetry metrics to MemoryCache. Follows the System.Net.Http pattern (#87319).

Fixes #124140

API Changes

Microsoft.Extensions.Caching.Abstractions

public class MemoryCacheStatistics
{
    public long TotalEvictions { get; init; } // NEW
}

Microsoft.Extensions.Caching.Memory

public class MemoryCacheOptions
{
    public string Name { get; set; } = "Default"; // NEW
}

public class MemoryCache
{
    // ILoggerFactory now nullable
    public MemoryCache(IOptions<MemoryCacheOptions> optionsAccessor, ILoggerFactory? loggerFactory);

    // NEW
    public MemoryCache(IOptions<MemoryCacheOptions> optionsAccessor, ILoggerFactory? loggerFactory, IMeterFactory? meterFactory);
}

Instruments

Meter: Microsoft.Extensions.Caching.Memory.MemoryCache

Instrument	Type	Dimensions
cache.requests	ObservableCounter<long>	cache.name, cache.request.type (hit/miss)
cache.evictions	ObservableCounter<long>	cache.name
cache.entries	ObservableUpDownCounter<long>	cache.name
cache.estimated_size	ObservableGauge<long>	cache.name

Design

• Gated on TrackStatistics — no instruments created unless TrackStatistics = true
• SharedMeter fallback — no IMeterFactory, no problem. Singleton SharedMeter with NOP Dispose. Same pattern as System.Net.Http.MetricsHandler.SharedMeter
• MeterOptions tags — factory path sets Tags = [new("cache.name", _options.Name)] for meter deduplication in DefaultMeterFactory
• WeakReference callbacks — observable callbacks capture WeakReference<MemoryCache>. Dead caches return empty measurements. No GC leaks
• IEnumerable overloads — Func<IEnumerable<Measurement<long>>> prevents phantom zero measurements from disposed or collected caches
• Eviction counting — RemoveEntry calls ConcurrentDictionary.TryRemove(KVP). Only the thread that removes the entry increments TotalEvictions. No double-counting
• DI unchanged — new constructor auto-selected. No changes to MemoryCacheServiceCollectionExtensions
• Conditional DiagnosticSource ref — in-box for net11.0+

Tests

• 142 tests pass (net11.0)
• 11 new metrics tests: instrument creation, SharedMeter fallback, null factory/logger, TrackStatistics gate, Name property, eviction accuracy, disposed cache, MeterOptions tags, over-count prevention
• 2 new eviction statistics tests

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-extensions-caching
See info in area-owners.md if you want to be subscribed.

[Copilot]

Pull request overview

Adds built-in OpenTelemetry metrics support to Microsoft.Extensions.Caching.Memory.MemoryCache by exposing additional cache statistics and wiring them into observable instruments, gated by MemoryCacheOptions.TrackStatistics.

Changes:

• Added TotalEvictions to MemoryCacheStatistics and tracked eviction counts in MemoryCache.
• Introduced MemoryCacheOptions.Name and new MemoryCache ctor overload supporting IMeterFactory.
• Added unit tests for metrics publication and eviction statistics, plus conditional DiagnosticSource references for non-inbox TFMs.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/libraries/Microsoft.Extensions.Caching.Memory/src/MemoryCache.cs	Implements eviction counting and publishes OTEL observable instruments via Meter/IMeterFactory.
src/libraries/Microsoft.Extensions.Caching.Memory/src/MemoryCacheOptions.cs	Adds Name option used as a metrics dimension.
src/libraries/Microsoft.Extensions.Caching.Memory/src/Microsoft.Extensions.Caching.Memory.csproj	Adds conditional DiagnosticSource reference for TFMs missing in-box metrics types.
src/libraries/Microsoft.Extensions.Caching.Memory/ref/Microsoft.Extensions.Caching.Memory.cs	Updates public API surface for new ctor overload and Name option.
src/libraries/Microsoft.Extensions.Caching.Memory/tests/MemoryCacheMetricsTests.cs	Adds tests validating instrument creation and basic measurements.
src/libraries/Microsoft.Extensions.Caching.Memory/tests/MemoryCacheGetCurrentStatisticsTests.cs	Adds tests for eviction statistics behavior.
src/libraries/Microsoft.Extensions.Caching.Memory/tests/Microsoft.Extensions.Caching.Memory.Tests.csproj	Adds conditional DiagnosticSource project reference for .NETFramework tests.
src/libraries/Microsoft.Extensions.Caching.Abstractions/src/MemoryCacheStatistics.cs	Adds TotalEvictions to the statistics snapshot type.
src/libraries/Microsoft.Extensions.Caching.Abstractions/ref/Microsoft.Extensions.Caching.Abstractions.cs	Updates ref assembly for TotalEvictions.

[cincuranet]

For the _accumulatedEvictions comments from Copilot, I think the idea with bool return is sound.

Or maybe putting the logic into RemoveEntry - given there's already _cacheSize handling - with a flag whether to count or not (not all RemoveEntry calls (should) update _accumulatedEvictions).

Up to you.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.

[Copilot]

InitializeMetrics creates 4 new observable instruments per MemoryCache instance. When an IMeterFactory is used, DefaultMeterFactory caches and returns the same Meter for the same name+tags; when no factory is provided, SharedMeter.Instance is a singleton. In both cases, creating multiple MemoryCache instances with the same options.Name will repeatedly add duplicate observable instruments to the same Meter with no way to unregister them, leading to unbounded instrument growth and potentially duplicated/incorrect metric streams. Consider ensuring instruments are created once per meter (e.g., static/once-init per meter) and have the observable callbacks aggregate across all caches sharing that meter/name (using a registry of weak references), rather than creating per-cache instruments.

Suggested change

	Tags = [new("cache.name", _options.Name)]
	Tags =
	[
	new("cache.name", _options.Name),
	new("cache.instance.id", RuntimeHelpers.GetHashCode(this))
	]

[rjmurillo]

Observable instruments on a shared Meter are not deduplicated. Each callback holds a WeakReference<MemoryCache>. GC collects a cache, the callback returns empty measurements. Cost is near zero.

Adding cache.instance.id breaks meter-level deduplication in DefaultMeterFactory. Different tags produce different meters. That defeats MeterOptions.Tags.

This follows the System.Net.Http.MetricsHandler.SharedMeter pattern from PR #87319. One to ten cache instances — instrument overhead is negligible.

@cincuranet confirmed the approach.