Endpoints

Endpoints Middleware

The App.Metrics.AspNetCore.Endpoints nuget package provides a set of middleware components which can be configured to expose endpoints whereby metric snapshots can be exposed over HTTP in different formats as well as information about the running environment of the application.

Endpoints Provided

The following lists the endpoints provided:

Endpoint Description
/metrics Exposes a metrics snapshot using the configured metrics formatter.
/metrics-text Exposes a metrics snapshot using the configured text formatter.
/env Exposes environment information about the application e.g. OS, Machine Name, Assembly Name, Assembly Version etc.

Both the /metrics and /metrics-text endpoints support content negotiation if mulitple formatters are configured, the thinking in providing both is that: /metrics-text could be used as a quick way to observe all recorded metrics in a human readable format using the Plain Text formatter from a browser when the /metrics endpoint used a type of binary formatter for example, or in cases like Prometheus’s scrape config where it might not be possible to modify the request headers when using mulitple metrics formatters.

How to use

App.Metrics.AspNetCore.Endpoints supports a couple ways to enable such endpoints 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.Endpoints

If bootstrapping with the Microsoft.AspNetCore.WebHost:

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

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

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

If bootstrapping in the Startup.cs:

public class Startup
{
    public void Configure(IApplicationBuilder app)
    {
        // To add all supported endpoints
        app.UseMetricsAllEndpoints();

        // Or to cherry-pick endpoint of interest
        // app.UseMetricsEndpoint();
        // app.UseMetricsTextEndpoint();
        // app.UseEnvInfoEndpoint();
    }

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

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

Configuration

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

Property Description
MetricsEndpointEnabled Allows enabling/disabling of the /metrics endpoint, when disabled will result in a 404 status code, the default is true.
MetricsTextEndpointEnabled Allows enabling/disabling of the /metrics-text endpoint, when disabled will result in a 404 status code, the default is true.
EnvironmentInfoEndpointEnabled Allows enabling/disabling of the /env endpoint, when disabled will result in a 404 status code, the default is true.
MetricsEndpointOutputFormatter The formatter used to serialize a snapshot of metrics when /metrics is requested.
MetricsTextEndpointOutputFormatter The formatter used to serialize a snapshot of metrics when /metrics-text is requested.
EnvInfoEndpointOutputFormatter The formatter used to serialize environment information when /env is requested.

Configure in code

Endpoint configuration can be applied using UseMetricsEndpoints():

...

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

...

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

Configure using IConfiguration

Endpoint configuration is automatically applied from the Microsoft.Extensions.Configuration.IConfiguration.

An appsettings.json can be used for example:

 "MetricEndpointsOptions": {
    "MetricsEndpointEnabled": true,
    "MetricsTextEndpointEnabled": true,
    "EnvironmentInfoEndpointEnabled": true
  }

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

Hosting Configuration

As well as the endpoint configuration above, the App.Metrics.AspNetCore.Endpoints nuget package includes endpoint hosting options:

Property Description
AllEndpointsPort Allows a port to be specified on which the configured endpoints will be available. This value will override any other endpoint port configuration.
EnvironmentInfoEndpoint The path to use for the environment info endpoint, the defaults is /env.
EnvironmentInfoEndpointPort The port to use for the environment info endpoint, if not specified uses your application’s default port.
MetricsEndpoint The path to use for the metrics endpoint, the defaults is /metrics.
MetricsEndpointPort The port to use for the metrics endpoint, if not specified uses your application’s default port.
MetricsTextEndpoint The path to use for the metrics text endpoint, the defaults is /metrics-text.
MetricsTextEndpointPort The port to use for the metrics text endpoint, if not specified uses your application’s default port.

To modify these configuration options, use the ConfigureAppMetricsHostingConfiguration() extension on the IHostBuilder:

...

.ConfigureAppMetricsHostingConfiguration(options =>
{
    options.AllEndpointsPort = 1111;
    options.MetricsEndpoint = "app-metrics";
});

...

When a custom port is defined on any or all of the endpoints, App Metrics will append the additional urls with the defined ports to the Microsoft.AspNetCore.Hosting.WebHostDefaults.ServerUrlsKey’s value.

Example Reponses

The following are example response generated by the App Metrics ASP.NET Core MVC sandbox project

metrics response using Plain Text formatting
metrics response using JSON formatting
env response using Plain Text formatting