Let consumers of MemoryCache access metrics #50406
Description
Background and Motivation
We want to add an API to expose memory cache statistics to allow consumers of caching to write their own EventSource/EventCounters and their own metrics.
Usage sample
Check out this gist: https://gist.github.com/maryamariyan/487816f724993c88a39fa29fe397aede
Approved API
The feature owners have agreed that they're willing to split the reference assembly to try out a Default Interface Method.
We also changed the statistics type to a class (partially from future expansion concerns).
public partial class MemoryCache
{
public MemoryCacheStatistics? GetCurrentStatistics() { throw null; }
}
public partial interface IMemoryCache
{
#if NET_7_OR_GREATER
public MemoryCacheStatistics? GetCurrentStatistics() => null;
#endif
}
public partial class MemoryCacheStatistics
{
public MemoryCacheStatistics() {}
public long TotalMisses { get; init; }
public long TotalHits { get; init; }
public long CurrentEntryCount { get; init; }
public long? CurrentEstimatedSize { get; init; }
}Original Description
## API suggestion public static partial class MemoryCacheExtensions
{
public static Microsoft.Extensions.Caching.Memory.MemoryCacheStatistics? GetCurrentStatistics(
this Microsoft.Extensions.Caching.Memory.MemoryCache memoryCache) { throw null; }
}
public partial struct MemoryCacheStatistics
{
public long CacheRequests { get; set; }
public long CacheHits { get; set; }
public long CacheCount { get; set; }
// public long EstimatedSize { get; set; } // consider adding later
}In contrast, System.Runtime.Caching already presented the following counters:
- Cache Total Entries / shows the total number of entries.
- Cache Total Hits / shows the number of times something was retrieved from the cache.
- Cache Total Misses / shows the number of times something was attempted to be retrieved from the cache but did not exist.
- Cache Total Hit Ratio / shows a ratio of the number of items found in the cache against the number of accesses.
- Cache Total Turnover Rate / is the number of items added to or removed from the cache per second.
Usage Examples
- Using metrics name
Microsoft.Extensions.Caching.Memory:
We would have metrics built-in using the proposed API. But developers would also be able to add their own event counters, using the proposed API.
As a developer, I may end up using GetCurrentStatistics in a callback passed down to a metrics API or an event counter.
We want MemoryCacheStatistics to help developer custom build their own metrics such as:
cacheRequestsPerSecond = (cacheRequestsAtTime2 - cacheRequestsAtTime1) / seconds_between_calls
or CacheHitRatio as CacheHits/CacheRequests.
Link to prototype here, does not use the API but shows how we could add built-in metrics.
Sample usage/screenshot for event counter:
[EventSource(Name = "Microsoft-Extensions-Caching-Memory")]
internal sealed class CachingEventSource : EventSource
{
/// ...
protected override void OnEventCommand(EventCommandEventArgs command)
{
if (command.Command == EventCommand.Enable)
{
if (_cacheHitsCounter == null)
{
_cacheHitsCounter = new PollingCounter("cache-hits", this, () =>
_memoryCache.GetCurrentStatistics().CacheHits)
{
DisplayName = "Cache hits",
};
}
}
}
}
Scope for this issue is:
- Add the proposed API
- Present code snippets that show how to use this API to add either event counters or System.Diagnostics.Metrics
Alternative Designs
Presented here, we'd be implementing EventSource ourselves in the assemblies.
Risks
The design assumes the metrics are cheap enough that we could track them all the time. If that is not the case then we'd want some APIs that turn the tracking on or subscribes.
TBA.
cc: @noahfalk