README.md

Prometheus.Client

.NET Client library for prometheus.io

It is hard fork of prometheus-net from early 2017 that has since evolved into a different library.

Our main goals:

• Keep possibility of rapid development.
• Extensibility is one of the core values, together with performance and minimal allocation.
• We are open for suggestions and new ideas, contribution is always welcomed.

Performance comparison with prometheus-net

Find more details on benchmarks description

Installation

dotnet add package Prometheus.Client

Extensions

Name	Description
Prometheus.Client.AspNetCore	ASP.NET Core middleware
Prometheus.Client.DependencyInjection	Dependency Injection extensions
Prometheus.Client.HttpRequestDurations	Metrics logging of request durations
Prometheus.Client.MetricPusher	Push metrics to Prometheus PushGateway
Prometheus.Client.MetricPusher.HostedService	MetricPusher as HostedService
Prometheus.Client.HealthChecks	HealthChecks Publisher
Prometheus.Client.MetricServer	Standalone Kestrel server
Prometheus.Client.Owin	Owin middleware

Use

Examples

Prometheus Docs

Add metrics endpoint without extension:

[Route("[controller]")]
public class MetricsController : Controller
{
    private readonly ICollectorRegistry _registry;

    public MetricsController(ICollectorRegistry registry)
    {
        _registry = registry;
    }

    [HttpGet]
    public async Task Get()
    {
        Response.StatusCode = 200;
        await using var outputStream = Response.Body;
        await ScrapeHandler.ProcessAsync(_registry, outputStream);
    }
}

Add metrics endpoint with Prometheus.Client.AspNetCore:

public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory, IApplicationLifetime appLifetime)
{
    app.UsePrometheusServer();
}

IMetricFactory and ICollectorRegistry can be added to DI container with Prometheus.Client.DependencyInjection:

public void ConfigureServices(IServiceCollection services)
{
    services.AddMetricFactory();
}

For collect http requests, use Prometheus.Client.HttpRequestDurations. It does not depend on Prometheus.Client.AspNetCore, however together it's very convenient to use:

public void Configure(IApplicationBuilder app, IHostingEnvironment env, ILoggerFactory loggerFactory, IApplicationLifetime appLifetime)
{
    app.UsePrometheusServer();
    app.UsePrometheusRequestDurations();
}

Instrumenting

Four types of metric are offered: Counter, Gauge, Summary and Histogram. See the documentation on metric types and instrumentation best practices on how to use them.

Counter

Counters go up, and reset when the process restarts.

var counter = metricFactory.CreateCounter("myCounter", "some help about this");
counter.Inc(5.5);

Gauge

Gauges can go up and down.

var gauge = metricFactory.CreateGauge("gauge", "help text");
gauge.Inc(3.4);
gauge.Dec(2.1);
gauge.Set(5.3);

Summary

Summaries track the size and number of events.

var summary = metricFactory.CreateSummary("mySummary", "help text");
summary.Observe(5.3);

Histogram

Histograms track the size and number of events in buckets. This allows for aggregate calculation of quantiles.

var hist = metricFactory.CreateHistogram("my_histogram", "help text", buckets: new[] { 0, 0.2, 0.4, 0.6, 0.8, 0.9 });
hist.Observe(0.4);

The default buckets are intended to cover a typical web/rpc request from milliseconds to seconds. They can be overridden passing in the buckets argument.

Labels

All metrics can have labels, allowing grouping of related time series.

See the best practices on naming and labels.

Taking a counter as an example:

var counter = metricFactory.CreateCounter("myCounter", "help text", labelNames: new []{ "method", "endpoint"});
counter.WithLabels("GET", "/").Inc();
counter.WithLabels("POST", "/cancel").Inc();

Since v4 there is alternative new way to provide a labels via ValueTuple that allow to reduce memory allocation:

var counter = metricFactory.CreateCounter("myCounter", "help text", labelNames: ("method", "endpoint"));
counter.WithLabels(("GET", "/")).Inc();
counter.WithLabels(("POST", "/cancel")).Inc();

Contribute

Contributions to the package are always welcome!

• Report any bugs or issues you find on the issue tracker.
• You can grab the source code at the package's git repository.

Supporters

We much appreciate free licenses provided by JetBrains to support our library.

License

All contents of this package are licensed under the MIT license.