Getting Started

Basics

App Metrics uses a simple C# fluent builder API to configure metrics. Core functionality is provided through an IMetrics interface. To build the interface use the MetricsBuilder. App Metrics core functionality is provided in the App.Metrics nuget package.

nuget install App.Metrics

var metrics = new MetricsBuilder()
    ... // configure options
.Build();

Recording Metrics

With an IMetrics instance we can record different types of metrics. The following example shows how to track a Counter using the metrics instance created in the above example.

var counter = new CounterOptions { Name = "my_counter" };
metrics.Measure.Counter.Increment(counter);

App Metrics includes various metric types each providing their own usefulness depending on the measurement being tracked.

Retrieving Metrics

The IMetrics interface allows us to retrieve a snapshot of recorded metrics.

var snapshot = metrics.Snapshot.Get();

Filtering Metrics

When retrieving a snapshot of currently recorded metrics, metrics can be filtered using the MetricsFilter which allows filtering by metric type, tags, name etc. To get a snapshot of all counters for example:

var filter = new MetricsFilter().WhereType(MetricType.Counter);
var snapshot = Metrics.Snapshot.Get(filter);

See filtering metrics for more details on the metrics filtering available.

Formatting Metrics

We can output metrics in different formats, by default a text formatter is applied. We can write the counter which was incremented in the previous example as follows:

using (var stream = new MemoryStream())
{
    await metrics.DefaultOutputMetricsFormatter.WriteAsync(stream, snapshot);
    var result = Encoding.UTF8.GetString(stream.ToArray());
    System.Console.WriteLine(result);
}

See formatting metrics for more details on the metrics formatting.

Environment Information

App Metrics also provides access to information of the current running environment such as the machine name, this environment information can be useful in tagging metrics.

var env = metrics.EnvironmentInfo;
var tags = new MetricTags("server", env.MachineName);
metrics.Measure.Counter.Increment(counter, tags);

Similarly outputing metrics, we can output the current environment information as follows:

using (var stream = new MemoryStream())
{
    await metrics.DefaultOutputEnvFormatter.WriteAsync(stream, metrics.EnvironmentInfo);
    var result = Encoding.UTF8.GetString(stream.ToArray());
    System.Console.WriteLine(result);
}

Reporting Metrics

Metrics are generally reported periodically, App Metrics reporters are distributed via nuget, this example uses the console reporter nuget package, which will allow reporting metrics in the default plain-text format to System.Console.

App Metrics supports a variety of metric reporters.

To use the console reporter, first install the nuget package:

nuget install App.Metrics.Reporting.Console

Then to enable console reporting:

var metrics = new MetricsBuilder()
    .Report.ToConsole()
    .Build();

The above will configure the console reporter but App Metrics will not schedule the reporting by default. This is to allow flexiblity in scheduling for different types of applications. App Metrics does however provide a task schedular which can be used to schedule the reporting of metrics via all configured reporters.

var scheduler = new AppMetricsTaskScheduler(
    TimeSpan.FromSeconds(3),
    async () =>
    {
        await Task.WhenAll(metrics.ReportRunner.RunAllAsync());
    });
scheduler.Start();

If integrating App Metrics in an ASP.NET Core application, install the App.Metrics.AspNetCore.All nuget package which schedules reporting via an Microsoft.Extensions.Hosting.IHostedService implementation.

Configuring a Console Application

Create a new dotnet core console application and install the App.Metrics and App.Metrics.Reporting.Console nuget packages.

nuget install App.Metrics
nuget install App.Metrics.Reporting.Console

Modify your Program.cs with the following:

public static class Program
{
    public static async Task Main()
    {
        var metrics = new MetricsBuilder()
            .Report.ToConsole()
            .Build();

        var counter = new CounterOptions { Name = "my_counter" };
        metrics.Measure.Counter.Increment(counter);

        await Task.WhenAll(metrics.ReportRunner.RunAllAsync());

        System.Console.ReadKey();
    }
}

In your .csproj add <LangVersion>latest</LangVersion> to allow the async Task Main method.