Prometheus Exporter AspNetCore for OpenTelemetry .NET

An OpenTelemetry Prometheus exporter for configuring an ASP.NET Core application with an endpoint for Prometheus to scrape.

[!WARNING] This component is still under development due to a dependency on the experimental Prometheus and OpenMetrics Compatibility specification and can undergo breaking changes before stable release. Production environments should consider using OpenTelemetry.Exporter.OpenTelemetryProtocol. Refer to the Getting Started with Prometheus and Grafana tutorial for more information.

[!IMPORTANT] The Prometheus scraping endpoint is not secured by default, so it is important to consider the security implications of exposing this endpoint in your application.

Refer to the Prometheus Security model and ASP.NET Core security documentation for more information and guidance on securing the Prometheus scraping endpoint to ensure only authorized users can access the information exposed by it.

Prerequisite

• Get Prometheus

Steps to enable OpenTelemetry.Exporter.Prometheus.AspNetCore

Step 1: Install Package

dotnet add package --prerelease OpenTelemetry.Exporter.Prometheus.AspNetCore

Step 2: Configure OpenTelemetry MeterProvider

• When using OpenTelemetry.Extensions.Hosting package on .NET 6.0+:

  services.AddOpenTelemetry()
      .WithMetrics(builder => builder.AddPrometheusExporter());
  

• Or configure directly:

  Call the MeterProviderBuilder.AddPrometheusExporter extension to register the Prometheus exporter.

  var meterProvider = Sdk.CreateMeterProviderBuilder()
      .AddPrometheusExporter()
      .Build();
  
  builder.Services.AddSingleton(meterProvider);
  

Step 3: Configure Prometheus Scraping Endpoint

You can use register the Prometheus scraping middleware using the MapPrometheusScrapingEndpoint extension method on IEndpointRouteBuilder interface with Minimal APIs. For example:

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.MapPrometheusScrapingEndpoint();

You can use the IEndpointConventionBuilder returned by the extension method to compose with other functionality, such as to exclude HTTP metrics from the scraping endpoint itself. For example:

app.MapPrometheusScrapingEndpoint()
   .DisableHttpMetrics();

If you are using the older Generic Host API you can register the Prometheus scraping middleware with the UseOpenTelemetryPrometheusScrapingEndpoint extension method on IApplicationBuilder instead:

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.UseOpenTelemetryPrometheusScrapingEndpoint();

Overloads of the UseOpenTelemetryPrometheusScrapingEndpoint extension are provided to change the path or for more advanced configuration a predicate function can be used:

app.UseOpenTelemetryPrometheusScrapingEndpoint(
        context => context.Request.Path == "/internal/metrics" &&
                   context.Connection.LocalPort == 5067);

This can be used in combination with configuring multiple ports on the ASP.NET application to expose the scraping endpoint on a different port.

Configuration

The PrometheusExporter can be configured using the PrometheusAspNetCoreOptions properties.

ScopeInfoEnabled

Specifies whether metrics include scope labels. Default value: true. Set to false to disable scope labels.

ScrapeEndpointPath

Defines the path for the Prometheus scrape endpoint for the middleware registered by MapPrometheusScrapingEndpoint and UseOpenTelemetryPrometheusScrapingEndpoint. Default value: "/metrics".

ScrapeResponseCacheDurationMilliseconds

Configures scrape endpoint response caching. Multiple scrape requests within the cache duration time period will receive the same previously generated response. The default value is 300. Set to 0 to disable response caching.

TargetInfoEnabled

Specifies whether to produce a target_info metric. Default value: true. Set to false to disable the target_info metric.

ResourceConstantLabels

A predicate used to select which resource attributes are added to each metric as constant labels. The predicate is invoked with the resource attribute key and should return true to include the attribute. Default value: null (no resource attributes are added as metric labels). Resource attributes copied as metric labels are always included in the target_info metric regardless of this predicate.

services.AddOpenTelemetry()
    .WithMetrics(builder => builder
        .AddPrometheusExporter(options =>
        {
            // Add all resource attributes as metric labels.
            options.ResourceConstantLabels = static _ => true;
        }));

TranslationStrategy

Controls how OpenTelemetry metric and label names are translated into Prometheus names, following the OpenTelemetry specification's translation_strategy option. The strategy combines two independent choices: whether discouraged characters are escaped to _ or UTF-8 names are passed through unaltered, and whether unit and type (e.g. _total) suffixes are appended.

The escaping choice only sets the default escaping scheme. A scrape request that negotiates an escaping scheme (via the escaping parameter of the Accept header, supported by the version 1.0.0 and later text formats) always takes precedence over the configured strategy. The classic (pre-1.0.0) text formats do not support escaping negotiation and are always emitted using underscore escaping; the suffix choice applies to every format.

Troubleshooting

This component uses an EventSource with the name "OpenTelemetry-Exporter-Prometheus" for its internal logging. Please refer to SDK troubleshooting for instructions on seeing these internal logs.

References

• OpenTelemetry Project
• Prometheus