Web Metrics

Tracking Middleware

The App.Metrics.AspNetCore.Tracking nuget package provides a set of middleware components which can be configured to automatically track typical metrics used in monitoring a web application.

Metrics Recorded

The tracking middleware records typical web application metrics which are summarized below.

Apdex

Monitors an Application Performance Index on the overall response times allowing us to monitor end-user satisfication.

Errors

The error middleware records the following error metrics:

  • The total number of error requests per http status code.
  • The percentage of overall error requests and percentage of each endpoints error requests.
  • An overall error request rate and error request rate per endpoint.
  • A overall count of each uncaught exception types.
  • A overall count of each uncaught exception types per endpoint.

There are several types of Gauges provided by App Metrics, a Hit Percentage Gauge is used for example to calculate the request error rate percentage by calculating the percentage of failed requests using the one minute rate of error requests and the one minute rate of overall web requests.

Throughput & Response Times

To measure the throughput and response times within a web application, Timers are registered to record:

  • The overall throughput and request duration of all routes.
  • The throughput and request duration per route within the web application.

POST and PUT request sizes

Histograms are used to track POST and PUT requests sizes of incomming HTTP requests.

OAuth2

If your web application is secured with OAuth2, by default App.Metrics will record metrics on a per client basis. This provides some useful insights into clients usage of your APIs. The OAuth2 middleware will record:

  • An overall and per endpoint request rate for each client.
  • An overall and per endpoint error rate for each client.
  • The POST and PUT request sizes for each client.

How to use

App.Metrics.AspNetCore.Tracking supports a couple ways to enable metrics tracking in an ASP.NET Core application:

  1. Using the Microsoft.Extensions.Hosting.Host in a Program.cs.
  2. Using the Microsoft.AspNetCore.Builder.IApplicationBuilder in a Startup.cs.

First install the nuget package:

nuget install App.Metrics.AspNetCore.Tracking

If bootstrapping with the Microsoft.Extensions.Hosting.Host:

This is a simpler approach as it will wire up the tracking middleware on the IApplicationBuilder, as well as tracking and metrics infrastructure on the IServiceCollection for you.

public static class Program
{
    public static IHost BuildHost(string[] args)
    {
        return Host.CreateDefaultBuilder(args)
                        .UseMetricsWebTracking()
                        .ConfigureWebHostDefaults(webBuilder =>
                        {
                            webBuilder.UseStartup<Startup>();
                        });
                        .Build();
    }

    public static void Main(string[] args) { BuildHost(args).Run(); }
}

Configuration options can be passed into UseMetricsWebTracking()

If bootstrapping in the Startup.cs:

public class Startup
{
    public void Configure(IApplicationBuilder app)
    {
        // To add all available tracking middleware
        app.UseMetricsAllMiddleware();

        // Or to cherry-pick the tracking of interest
        // app.UseMetricsActiveRequestMiddleware();
        // app.UseMetricsErrorTrackingMiddleware();
        // app.UseMetricsPostAndPutSizeTrackingMiddleware();
        // app.UseMetricsRequestTrackingMiddleware();
        // app.UseMetricsOAuth2TrackingMiddleware();
        // app.UseMetricsApdexTrackingMiddleware();
    }

    public void ConfigureServices(IServiceCollection services)
    {
        var metrics = AppMetrics.CreateDefaultBuilder()
            ... // configure other options
            .Build();

        services.AddMetrics(metrics);
        services.AddMetricsTrackingMiddleware();
    }
}

Configuration

The App.Metrics.AspNetCore.Tracking nuget package supports the following configuration:

Property Description
IgnoredRoutesRegexPatterns An list of regex patterns used to ignore matching routes from metrics tracking.
OAuth2TrackingEnabled Allows recording of all OAuth2 Client tracking to be enabled/disabled. Defaults to true.
ApdexTrackingEnabled Allows enabling/disabling of calculating the Apdex score on the overall responses times. Defaults to true.
ApdexTSeconds The Apdex T seconds value used in calculating the score on the samples collected.
IgnoredHttpStatusCodes Allows specific http status codes to be ignored when reporting on response related information, e.g. You might not want to monitor 404 status codes.

Configure in code

Tracking configuration can be applied using UseMetricsWebTracking():

...

.UseMetricsWebTracking(options =>
{
    // apply configuration options
});

...

The configuration set with Microsoft.Extensions.Configuration.IConfiguration will override any code configuration.

Configure using IConfiguration

Web Tracking configuration is automatically applied from the Microsoft.Extensions.Configuration.IConfiguration.

An appsettings.json can be used for example:

  "MetricsWebTrackingOptions": {
    "ApdexTrackingEnabled": true,
    "ApdexTSeconds": 0.1,
    "IgnoredHttpStatusCodes": [ 404 ],
    "IgnoredRoutesRegexPatterns": [],
    "OAuth2TrackingEnabled": true
  },

At the moment formatters cannot be configured via configuration setting files.