UnifiedMonitoring.Toolkit 0.1.6

Introduction

To create observability coherency across applications, the Unified Monitoring Toolkit can be used in .NET applications. The package instruments the application and is set up to export telemetry using OpenTelemetry protocol.

The Golden Signals

The Golden Signals are four key metrics used to monitor the health and performance of distributed systems, especially in cloud-native environments like microservices. They help teams observe and diagnose issues effectively. These signals are:

• Latency: The time it takes to service a request. High latency may indicate performance bottlenecks.
• Traffic: The demand or load on the system, often measured in requests per second or throughput.
• Errors: The rate of failed requests, which reveals issues in the system’s reliability.
• Saturation: How full the system’s resources (like CPU, memory) are, indicating whether the system is nearing its capacity.

Importance in Observation:

• Latency shows performance issues.
• Traffic reflects demand, helping with capacity planning.
• Errors highlight reliability concerns.
• Saturation helps avoid overload and ensures resource efficiency.

Together, they provide a comprehensive view of system health, making it easier to detect, diagnose, and respond to issues quickly.

In order to track and measure on the Golden Signals, the Unified Monitoring Toolkit utilizes The Three Pillars of Observability:

• Logs
• Metrics
• Distributed Traces

Initial Setup

Prerequisites

.NET applications should be at least .NET 8.0 or later.

An OpenTelemetry Collectors endpoint to deliver telemetry to. Link

Quick Start

In order to start using the instrumentation, all that is needed is to add it to the WebApplication builder and provide a service name and the endpoint for the OpenTelemetry Collector:

using UnifiedMonitoring.Toolkit;

var builder = WebApplication.CreateBuilder(args);
builder.AddMonitoring(config =>
    {
        config.ServiceName = "MyAppName";
        config.OtlpEndpoint = builder.Configuration.GetConnectionString("otlp-endpoint");
    });

Traces filtering (Optional)

By default, all traces are logged, with the exception of health checks on standard endpoints. The package offers option to filter out specific endpoints, that starts or ends with a unique string pattern. This can be useful to remove tracing of irrelevant information, such as feature flag calls. Note that these filters are only for successful requests, erroneous requests are still traced.

Example of using tracer filters:

using UnifiedMonitoring.Toolkit;

var builder = WebApplication.CreateBuilder(args);
builder.AddMonitoring(config =>
    {
        config.ServiceName = "MyAppName";
        config.OtlpEndpoint = builder.Configuration.GetConnectionString("otlp-endpoint");
        config.TracingParameters = new TracingParameters
        {
            Filters = new FilterParameters[]
            {
                new FilterParameters
                {
                    Mode = FilterMode.StartsWith,
                    FilterString = "feature-flags"
                }
            }
        };
    });

Custom instrumentation

Using the interface IDiagnosticsConfig, its possible to do custom instrumentation of your codebase.

The interface provides abstraction of .NET System.Diagnostics methods and provide a simplified way of creating spans and metrics.

For more in depth information, see Microsoft documentation on how to use Meter and Activity.

Custom Metrics

The package only provides an abstraction of System.Diagnostics Meter class. The GetMeter method, returns a initialized Meter with the context of the service.

Using this method to generate your own custom metrics will automatically add it to the metrics exporter in the package.

Example of using the meter:

public interface ICustomMetrics
{
    void AddToCounter(string name, int value);
}

public class CustomMetrics(IDiagnosticsConfig diagnosticsConfig) : ICustomMetrics
{
    public void AddToCounter(string name, int value)
    {
        diagnosticsConfig.GetMeter().CreateCounter<long>(name).Add(value);
    }
}

Custom Spans

IDiagnosticsConfig abstracts away the need for creating ActivitySources and provides the Activity when started.

By default, the calling methods name is set a name of the Activity.

Adding metadata to your span:

using System.Diagnostics;
using UnifiedMonitoring.Toolkit;

public void MyMethod(IDiagnosticsConfig diagnosticsConfig) {
    using var activity = diagnosticsConfig.StartActivity(); // Provide a string for naming the activity or leave it empty to default to the method name.

    activity?.AddTag("customer.customernumber", "1234"); //Tags are equivalent to attributes in OpenTelemetry
    activity?.AddEvent(new ActivityEvent("Something happend!")); //Events are equivalent to events in OpenTelemetry
    
}

Adding exception raising to tracing:

using System.Diagnostics;
using UnifiedMonitoring.Toolkit;

public void MyMethod(IDiagnosticsConfig diagnosticsConfig) {
    using var activity = diagnosticsConfig.StartActivity(); // Provide a string for naming the activity or leave it empty to default to the method name.

    try
    {
        do something...
    }
    catch(Exception e)
    {
        activity?.SetStatus(ActivityStatusCode.Error)
        throw;
    }
}

Wolverine Metrics (Link)

UnifiedMonitoring.Toolkit also provides autoinstrumentation when using Wolverine for event messaging.

It's important that the service name is the same for both the Wolverine implemenntation, as well as with the monitoring implementation.

var builder = WebApplication.CreateBuilder(args);
builder.AddMonitoring(config =>
    {
        config.ServiceName = "MyAppName";
        config.OtlpEndpoint = builder.Configuration.GetConnectionString("otlp-endpoint");
    });

builder.Host.UseWolverine(options =>
{
    options.ServiceName = "MyAppName";
    ...
});

Instrumentation of GraphQL Server (Link)

In order for the GraphQL Server to be instrumented, you need to opt-in on instrumentation when adding the Server to the ServiceCollection.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddGraphQLServer()
            ...
            .AddInstrumentation();

License

This project is licensed under the Apache License, Version 2.0 - see the LICENSE file for details.

Third-Party Dependencies

This project uses the following third-party libraries:

• HotChocolate.Diagnostics - Licensed under MIT License (© ChilliCream)
• Microsoft.Extensions.DependencyInjection - Licensed under MIT License (© Microsoft Corporation)
• Microsoft.Extensions.Diagnostics.HealthChecks - Licensed under MIT License (© Microsoft Corporation)
• Microsoft.Extensions.Diagnostics.ResourceMonitoring - Licensed under MIT License (© Microsoft Corporation)
• Npgsql.OpenTelemetry - Licensed under PostgreSQL License (© The Npgsql Development Team)
• OpenTelemetry (and associated packages) - Licensed under Apache License, Version 2.0 (© OpenTelemetry Authors)
• Serilog (and associated packages) - Licensed under Apache License, Version 2.0 (© Serilog contributors)

Refer to their respective licenses for more information.