Autometrics-CS is a C# instrumentation of the Autometrics observability micro-framework. It makes it quick and easy to instrument your code to collect standardized metrics, including function call counts, durations, and build information. This project includes a sample application which shows examples for generating metrics to the console, Prometheus, or hosting and endpoint for scraping.
- Aspect-Oriented Programming and AspectInjector
- How it Works
- Getting Started
- Examples
- Running the Sample Console Application and looking at the Grafana Dashboards
Autometrics-CS utilizes Aspect-Oriented Programming (AOP) techniques to provide non-invasive and modular instrumentation. AOP allows you to inject additional behavior (in our case, metrics collection) into your methods without altering the original code. This project uses the AspectInjector library to achieve AOP in C#.
Metrics instrumentation is performed using Microsoft's System.Diagnostics.Metrics library. This provides a lightweight and well-tested method of instrumentation that's used as a .NET standard.
Read more on Microsoft's Metrics Overview page.
When using System.Diagnostics.Metrics, the metrics instrumentation occurs but the data isn't listened to or sent anywhere. We've provided examples below of using OpenTelemetry's .NET exporters to export this data in an Otel-friendly format. Additional options such as using the dotnet-counters command-line tool or the MeterListener API can be seen on the Metrics Collection page.
To use Autometrics, follow these simple steps:
- Import the Autometrics package and its dependencies in your code.
- Add the
[Autometrics]attribute and any SLOs to the methods you want to instrument. - Configure the Collection method and Exporter in your application.
The instrumentation attribute can be added to any method and its usage doesn't change for Libraries, Console Applications, or Web Applications. The only difference is how the metrics are exported. The attribute class is AutometricsAttribute, however Visual Studio will show it as only Autometrics.
[Autometrics]
private bool CheckRedisCache()
{
// Your unchanged code here
}The instrumentation attribute can be added to classes and will apply to all methods within a class. The SkipInjection attribute from the AspectInjector package can be added to methods to prevent them from being instrumented.
[Autometrics]
public class BusinessLayer
{
public DataAccessLayer? DataAccessLayer { get; set; }
public void ProcessRequest()
{
// Your instrumented code here
}
[SkipInjection]
public void CalculateShippingCost()
{
// Your non instrumented code here
}
}Autometrics makes it easy to add Prometheus Service-Level Objectives (SLOs) to your methods. SLOs are a great way to track the performance of your code and ensure that it meets your expectations. SLOs can be added as three different types:
Success Rate: The percentage of calls that succeed.
[Autometrics("UserAuth", ObjectivePercentile.P99)]
public void UserAuthentication()
{
// Your code here
}Latency Threshold: The amount of time it takes for a call to complete.
[Autometrics("OrderCreation", ObjectivePercentile.P99, ObjectiveLatency.Ms500, ObjectiveType.LatencyThreshold)]
public void OrderGeneration()
{
// Your code here
}Both Latency and Success Rate: The amount of time it takes for a call to complete and the percentage of calls that succeed. This is the default if a ObjectiveLatency is specifyed but no ObjectiveType is specified.
[Autometrics("OrderCreation", ObjectivePercentile.P99, ObjectiveLatency.Ms500, ObjectiveType.SuccessAndLatency)]
public void OrderGeneration()
{
// Your code here
}Check out the Autometrics.Samples projects for examples of how to use Autometrics in your code. Varying examples of how this works and using it can be seen on the ConsoleApp Sample, Library Sample, and WebApp Sample pages. page.
The Autometrics Instrumentation works well in a library, and the metrics module tag will hold the libraries name when used as a dependency. No exporter configuration is required within the library, the application using the library will be responsible for exporting the metrics.
A library instrumented with Autometrics can be used in an application that doesn't add a meter or listen to those metrics.
Here's an example of how to instrument Autometrics in a C# Console application and export the metrics to the OpenTelemetry collector.
using OpenTelemetry;
namespace MyProject
{
class Program
{
static void Main(string[] args)
{
// Create a meter provider with the Otlp exporter connected to the Autometrics.Instrumentation
using var meterProvider = Sdk.CreateMeterProviderBuilder()
.AddMeter("Autometrics.Instrumentation")
.AddOtlpExporter()
.Build();
// Call your instrumented method(s)
MyInstrumentedMethod();
}
}
}Here's and example of exporting the metrics to the OpenTelemetry collector in a C# Web application.
using OpenTelemetry;
using OpenTelemetry.Metrics;
using OpenTelemetry.Trace;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddRazorPages();
// Add OpenTelemetry services, and configure the metrics exporter for Autometrics.Instrumentation
builder.Services.AddOpenTelemetry()
.WithMetrics(builder =>
{
// Additional configuration or other exporters can be added here
builder.AddOtlpExporter();
builder.AddMeter("Autometrics.Instrumentation");
});
var app = builder.Build();
if (!app.Environment.IsDevelopment())
{
app.UseExceptionHandler("/Error");
app.UseHsts();
}
app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthorization();
app.MapRazorPages();
app.MapControllers();
app.Run();Running the application generates a steady flow of activity with the ocassional error
The pre-build Grafana Dashboards display the activity the same as all over Autometrics projects
