ServiceLevelIndicators 8.0.0-alpha.7

ArtifactType: nupkg. Language: csharp. Tags: SLI, OpenTelemetry, Metrics.

Service Level Indicators

Service level indicators (SLIs) are metrics used to measure the performance of a service. They are typically used in the context of service level agreements (SLAs), which are contracts between a service provider and its customers that define the expected level of service. SLIs are used to track the actual performance of the service against the agreed upon SLA.

There are many different types of SLIs that can be used to measure the performance of a service. Some common examples include:

• Availability: This measures the percentage of time that a service is available and functioning properly.
• Response time: This measures the amount of time it takes for a service to respond to a request.
• Throughput: This measures the amount of work that a service can handle in a given period of time.
• Error rate: This measures the percentage of requests that result in errors.

SLIs are important because they provide a way to objectively measure the performance of a service. By tracking SLIs over time, service providers can identify trends and make improvements to the service to ensure that it meets the needs of its customers.

Service Level Indicator Library

Service Level Indicator library will help emit latency metrics for each API operation to help monitor the service performance over time. The metrics is emitted via standard .NET Meter Class.

By default, an instrument named LatencySLI is added to the service metrics and the metrics are emitted. The metrics are emitted with the following attributes.

• CustomerResourceId - The customer resource id.
• LocationId - The location id of where the service running. eg. Public cloud, West US 3 region.
• Operation - The name of the operation. Defaults to AttributeRouteInfo.Template information like GET Weatherforecast.
• activity.status_code - The activity status code tells if the operation succeeded or failed. ActivityStatusCode.

ServiceLevelIndicators.Asp adds the following dimensions.

• The activity status code will be "Ok" when the http response status code is in the 2xx range, "Error" when the http response status code is in the 5xx range, "Unset" for any other status code.
• http.response.status_code - The http status code.
• http.request.method (Optional)- The http request method (GET, POST, etc) is added.
• http.api.version (Optional)- API Version when used in conjunction with API Versioning package.

NuGet Packages

• ServiceLevelIndicators

  This library can be used to emit SLI for all .net core applications, where each operation is measured.

  

• ServiceLevelIndicators.Asp

  For measuring SLI for ASP.NET Core applications use this library that will automatically measure each API operation.

  

• ServiceLevelIndicators.Asp.ApiVersioning

  If API Versioning package is used, this library will add the API version as a metric dimension.

  

Usage for Web API MVC

1. Create and register a metrics meter with the dependency injection.

   Example.

   public class SampleApiMeters
   {
       public const string MeterName = "SampleMeter";
       public Meter Meter { get; } = new Meter(MeterName);
   }
   builder.Services.AddSingleton<SampleApiMeters>();
   

2. Add a class to configure SLI

   Example.

   internal sealed class ConfigureServiceLevelIndicatorOptions : IConfigureOptions<ServiceLevelIndicatorOptions>
   {
       private readonly SampleApiMeters meters;
       public ConfigureServiceLevelIndicatorOptions(SampleApiMeters meters) => this.meters = meters;
       public void Configure(ServiceLevelIndicatorOptions options) => options.Meter = meters.Meter;
   }
   
   builder.Services.TryAddEnumerable(ServiceDescriptor.Singleton<IConfigureOptions<ServiceLevelIndicatorOptions>,
       ConfigureServiceLevelIndicatorOptions>());
   

3. Add ServiceLevelIndicator with MVC, into the dependency injection.

   Example.

   builder.Services.AddServiceLevelIndicator(options =>
   {
       // Override with calling service id or customer Id.
       options.CustomerResourceId = ServiceLevelIndicator.CreateCustomerResourceId(serviceId);
       options.LocationId = ServiceLevelIndicator.CreateLocationId("public", "westus2");
   })
   .AddMvc();
   

4. Add the middleware to the pipeline.

   app.UseServiceLevelIndicator();
   

Usage for Minimal API

1. Create the metrics meter.

   Example.

   internal sealed class Sample
   {
       public static Meter Meter { get; } = new(nameof(Sample));
   }
   

2. Add ServiceLevelIndicator into the dependency injection.

   Example.

   builder.Services.AddServiceLevelIndicator(options =>
   {
       // Override with calling service id or customer resource Id.
       options.CustomerResourceId = ServiceLevelIndicator.CreateCustomerResourceId(serviceId);
       options.LocationId = ServiceLevelIndicator.CreateLocationId("public", "westus2");
   });
   

3. Add the middleware to the ASP.NET core pipeline.

   Example.

   app.UseServiceLevelIndicator();
   

4. To each API route mapping, add AddServiceLevelIndicator()

   Example.

   app.MapGet("/hello", () => "Hello World!")
      .AddServiceLevelIndicator();
   

Usage for background jobs

You can measure a block of code by boxing it in a using clause of MeasuredOperation. Example.

    async Task MeasureCodeBlock(ServiceLevelIndicator serviceLevelIndicator)
    {
        using var measuredOperation = serviceLevelIndicator.StartLatencyMeasureOperation("OperationName");
        // Do Work.
        measuredOperation.SetActivityStatusCode(System.Diagnostics.ActivityStatusCode.Ok);
    }

Customizations

Once the Prerequisites are done, all controllers will emit SLI information. The default operation name is in the format <HTTP Method> <Controller>/<Action>. eg GET WeatherForecast/Action1

• To add API versioning as a dimension use package ServiceLevelIndicators.Asp.ApiVersioning and enrich the metrics with AddApiVersionEnrichment.

  Example.

  builder.Services.AddServiceLevelIndicator(options =>
  {
      /// Options
  })
  .AddMvc()
  .AddApiVersionEnrichment();
  

• To add HTTP method as a dimension, add AddHttpMethodEnrichment to Service Level Indicator.

  Example.

  builder.Services.AddServiceLevelIndicator(options =>
  {
      /// Options
  })
  .AddMvc()
  .AddHttpMethodEnrichment();
  

• To override the default operation name add the attribute [ServiceLevelIndicator] and specify the operation name.

  Example.

  [HttpGet("MyAction2")]
  [ServiceLevelIndicator(Operation = "MyOperation")]
  public IEnumerable<WeatherForecast> GetOperation() => GetWeather();
  

• To override the CustomerResourceId within an API method, mark the parameter with the attribute [CustomerResourceId]

      [HttpGet("get-by-zip-code/{zipCode}")]
      public IEnumerable<WeatherForecast> GetByZipcode([CustomerResourceId] string zipCode) => GetWeather();
  

  Or use GetMeasuredOperationLatency extension method.

  [HttpGet("{customerResourceId}")]
  public IEnumerable<WeatherForecast> Get(string customerResourceId)
  {
      HttpContext.GetMeasuredOperationLatency().CustomerResourceId = customerResourceId;
      return GetWeather();
  }
  

• To add custom Open Telemetry attributes.

      HttpContext.GetMeasuredOperationLatency().AddAttribute(attribute, value);
  

  GetMeasuredOperationLatency will throw if the route is not configured to emit SLI.

  When used in a middleware or scenarios where a route may not be configured to emit SLI.

      if (HttpContext.TryGetMeasuredOperationLatency(out var measuredOperationLatency))
          measuredOperationLatency.AddAttribute("CustomAttribute", value);
  

  You can add additional dimensions to the SLI data by using the Measure attribute.

  [HttpGet("name/{first}/{surname}")]
  public IActionResult GetCustomerResourceId([Measure] string first, [CustomerResourceId] string surname) => Ok(first + " " + surname);
  

• To prevent automatically emitting SLI information on all controllers, set the option,

      ServiceLevelIndicatorOptions.AutomaticallyEmitted = false;
  

  In this case, add the attribute [ServiceLevelIndicator] on the controllers that should emit SLI.

• To measure a process, run it within a using StartLatencyMeasureOperation block.

  Example.

  public void StoreItem(MyDomainEvent domainEvent)
  {
      var attribute = new KeyValuePair<string, object?>("Event", domainEvent.GetType().Name);
      using var measuredOperation = _serviceLevelIndicator.StartLatencyMeasureOperation("StoreItem", attribute);
      DoTheWork();
  

Sample

Try out the sample weather forecast Web API.

To view the metrics locally.

1. Run Docker Desktop
2. Run sample\DockerOpenTelemetry\run.cmd to download and run zipkin and prometheus.
3. Run the sample web API project and call the GET WeatherForecast using the Open API UI.
4. You should see the SLI metrics in prometheus under the meter LatencySLI_bucket where the Operation = "GET WeatherForeCase", http.response.status.code = 200, LocationId = "ms-loc://az/public/westus2", activity.status_code = Ok
5. If you run the sample with API Versioning, you will see something similar to the following.