JoeShook.ZiggyCreatures.FusionCache.Metrics.AppMetrics 1.0.4

.NET Standard 2.0
Install-Package JoeShook.ZiggyCreatures.FusionCache.Metrics.AppMetrics -Version 1.0.4
dotnet add package JoeShook.ZiggyCreatures.FusionCache.Metrics.AppMetrics --version 1.0.4
<PackageReference Include="JoeShook.ZiggyCreatures.FusionCache.Metrics.AppMetrics" Version="1.0.4" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add JoeShook.ZiggyCreatures.FusionCache.Metrics.AppMetrics --version 1.0.4
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
#r "nuget: JoeShook.ZiggyCreatures.FusionCache.Metrics.AppMetrics, 1.0.4"
#r directive can be used in F# Interactive, C# scripting and .NET Interactive. Copy this into the interactive tool or source code of the script to reference the package.
// Install JoeShook.ZiggyCreatures.FusionCache.Metrics.AppMetrics as a Cake Addin
#addin nuget:?package=JoeShook.ZiggyCreatures.FusionCache.Metrics.AppMetrics&version=1.0.4

// Install JoeShook.ZiggyCreatures.FusionCache.Metrics.AppMetrics as a Cake Tool
#tool nuget:?package=JoeShook.ZiggyCreatures.FusionCache.Metrics.AppMetrics&version=1.0.4
The NuGet Team does not provide support for this client. Please contact its maintainers for support.

FusionCache.AppMetrics

<div align="center">

FusionCache logo

License: MIT Twitter badge </div>

FusionCache.AppMetrics is a plugin to capture caching metrics using FusionCache

Metrics are missing from open-source resiliency projects in the .NET ecosystem where in equivalent Java libraries, metrics tend to be common. FusionCache is a feature rich caching library addressing resiliency needs of today’s enterprise implementations. Appmetrics is an easy-to-use metrics library that works in .NET Framework and .NET Core. Joining these two excellent libraries together you can easily be caching and writing metrics to your favorite timeseries database.

Usage


    var hostNameCache = new MemoryCache(new MemoryCacheOptions());
    var appMetricsContextLabel = "MyApplication";

    var appMetrics = new MetricsBuilder()
        .Configuration.Configure(
            options =>
            {
                options.DefaultContextLabel = appMetricsContextLabel;
            })
        .Report
        .ToInfluxDb(
            options =>
            {
                var filter = new MetricsFilter();
                filter.WhereContext(c => c == appMetricsContextLabel); //remove default AppMetrics metrics.
                options.InfluxDb.BaseUri = new Uri($"http://{ Configuration["InfluxDbConfig.Host"] }:{ Configuration["InfluxDbConfig.Port"] }");
                options.InfluxDb.Database = Configuration["InfluxDbConfig.Database"];
                options.InfluxDb.RetentionPolicy = Configuration["InfluxDbConfig.RetentionPolicy"];
                options.InfluxDb.UserName = Configuration["InfluxDbConfig.Username"];
                options.InfluxDb.Password = Configuration["InfluxDbConfig.Password"];
                options.InfluxDb.CreateDataBaseIfNotExists = false;
                options.MetricsOutputFormatter = new MetricsInfluxDbLineProtocolOutputFormatter(
                    new MetricsInfluxDbLineProtocolOptions
                    {
                        MetricNameFormatter = (metricContext, metricName) => $"{appMetricsContextLabel}_{metricContext}"
                    });
            })
        // .Report.ToTextFile(
        //     options => {
        //         options.MetricsOutputFormatter = new MetricsJsonOutputFormatter();
        //         options.AppendMetricsToTextFile = true;
        //         // options.Filter = filter;
        //         options.FlushInterval = TimeSpan.FromSeconds(20);
        //         options.OutputPathAndFileName = @"C:\temp\metrics.txt";
        //     })
        .Build();
        
        //
        // Cache called "domain"
        //
        // Register AppMetricsProvider as a IFusionCachePlugin.
        // Note that a MemoryCache object must be created outside of AddFusionCache extension method so that
        // AppMetricsProvider is holding the same object as FusionCache to enabled cache count reporting.
        // See line 180 in FusionCacheEventSource.cs
        //
        services.AddSingleton<IMemoryCache>(hostNameCache);
        services.AddSingleton<IFusionCachePlugin>(new AppMetricsProvider("domain", appMetrics, hostNameCache));
        services.AddFusionCache(options =>
            options.DefaultEntryOptions = new FusionCacheEntryOptions
            {
                Duration = TimeSpan.FromSeconds(1),
                JitterMaxDuration = TimeSpan.FromMilliseconds(200),
                IsFailSafeEnabled = true,
                FailSafeMaxDuration = TimeSpan.FromHours(1),
                FailSafeThrottleDuration = TimeSpan.FromSeconds(1),
                FactorySoftTimeout = TimeSpan.FromMilliseconds(100), 
                FactoryHardTimeout = TimeSpan.FromSeconds(1)
            });
                
        var metricsReporterService = new MetricsReporterBackgroundService(appMetrics, appMetrics.Options, appMetrics.Reporters);
        metricsReporterService.StartAsync(CancellationToken.None);
        services.AddSingleton(sp => metricsReporterService );

AppMetrics Plugin is an easy to use solution for .NET Framework apps. If you already use AppMetrics then this would be an easy way to go.

There are two example WebApi style projects included:

Metrics plugins are created by subscribing to FusionCache Events.

MetricsConfig

MetricsConfig contains the following properties and can be overriden by adding a CacheMetrics section to appsettings.json.

  • ApplicationName is defaulted to the executing assembly name.

  • ApplicationVersion is defaulted to the executing assembly version.

  • Prefix is defaulted to "appMetrics"

  • MeasurementName is defaulted to "Cache-Events"

    see Examples for usage

The following Events are subscribed to. Each event includes a Tag named "cacheEvent" and a tag value. Both the "cacheEvent" name and Tag values are defined in the SemanticConventions class. These conventions can be changed by implementing a new ISemanticConventions interface and registering in you dependency injection framework. Tags are typical in time series databases and are indexed making them friendly to searching and grouping over time.

Events:: Incrementing Polling Counters for Hits and Misses

The following counters all set AppMetrics's CounterOptions for ResetOnReporting to true. The effect is each time a reporter queries the counter it will be reset. All the following counters accept the CacheCountIncrement and CacheCountDecrement set ResetOnReporting to true.

CacheHit()

The cache tag is "HIT". Every cache hit will increment a counter.

CacheMiss()

The cache tag is "MISS". Every cache miss will increment a counter.

CacheStaleHit()

The cache tag is "STALE_HIT". When FailSafe is enabled and a request times out due to a "soft timeout" and a stale cache item exists then increment a counter. Note this will not trigger the CacheMiss() counter.

CacheBackgroundRefresh()

The cache tag is "STALE_REFRESH". When FailSafe is enabled and a request times out due to a "soft timeout" the request will continue for the length of a "hard timeout". If the request finds data it will call this CacheBackgroundRefresh() and increment a counter. Note it would be normal for this counter and CacheStaleHit() to track with eachother.

CacheRemoved()

The cache tag is "REMOVE". When the cache is removed by user code.

Incrementing Polling Counter for Evictions

Eviction counters are wired into the ICacheEntries with the PostEvictionDelegate.

CacheExpired

The cache tag is "EXPIRE". When the EvictionReason is Expired increment a counter.

CacheCapacityExpired()

The cache tag is "CAPACITY". When the EvictionReason is Capacity increment a counter.

Events:: Polling Counters

CacheCount()

The cach tag is "ITEM_COUNT". Calls the MemoryCache.Count

For this feature MemoryCache must be created and passed to FusionCache and AppMetricsProvider so they share the same intance of MemoryCache

Product Versions
.NET net5.0 net5.0-windows net6.0 net6.0-android net6.0-ios net6.0-maccatalyst net6.0-macos net6.0-tvos net6.0-windows
.NET Core netcoreapp2.0 netcoreapp2.1 netcoreapp2.2 netcoreapp3.0 netcoreapp3.1
.NET Standard netstandard2.0 netstandard2.1
.NET Framework net461 net462 net463 net47 net471 net472 net48
MonoAndroid monoandroid
MonoMac monomac
MonoTouch monotouch
Tizen tizen40 tizen60
Xamarin.iOS xamarinios
Xamarin.Mac xamarinmac
Xamarin.TVOS xamarintvos
Xamarin.WatchOS xamarinwatchos
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.0.4 61 5/2/2022
1.0.3 70 2/20/2022
1.0.3-preview001 391 12/6/2021
1.0.2 873 12/1/2021
1.0.0 181 7/26/2021
1.0.0-preview003 135 7/23/2021
1.0.0-preview002 156 7/22/2021
1.0.0-preview001 107 7/20/2021

Update to FusionCache v0.9