Tracking Custom Events and Metrics with Application Insights SDK

1. Custom Events vs. Custom Metrics

Before we write any code, it's vital to understand the distinction between custom events and custom metrics. They serve different purposes and are stored and optimized differently within Application Insights.

To summarize the key difference:

• Custom Events: Represent discrete occurrences. Use them to count things that happen, like a user clicking a button, a file being generated, or a specific business rule being triggered.
• Custom Metrics: Represent numeric measurements over time. Use them to track values you want to aggregate, such as averages, sums, or percentiles. Examples include shopping cart totals, queue lengths, or calculation durations.

2. The TelemetryClient: Your Gateway to Custom Telemetry

The primary tool for sending custom telemetry from your .NET application is the TelemetryClient class, which is part of the Application Insights SDK.

In modern ASP.NET Core applications, the best practice is to get an instance of TelemetryClient via dependency injection (DI). Since you've already configured Application Insights in your project (either via AddApplicationInsightsTelemetry() or UseAzureMonitor()), the DI container knows how to create and provide this object for you.

You simply request it in the constructor of your controller or service:

private readonly TelemetryClient _telemetryClient;

public MyController(TelemetryClient telemetryClient)
{
    _telemetryClient = telemetryClient;
}

The video below explains this process.

3. Tracking Custom Events

With your TelemetryClient instance, you can now track custom events using the TrackEvent method.

A custom event can include:

1. Event Name (required): A string that identifies the event (e.g., "ItemAddedToCart").
2. Properties (optional): A Dictionary<string, string> for adding contextual, filterable information. These are stored in the customDimensions field.
3. Metrics (optional): A Dictionary<string, double> for attaching numeric measurements to the event. These are stored in the customMeasurements field.

The following video demonstrates tracking a simple event and then enhancing it with custom properties.

OpenTelemetry Equivalent

If you are using the modern OpenTelemetry setup, you can still track custom events. The OTel-native way is to use the standard ILogger interface and add a special attribute to your log message.

// Using ILogger to send a custom event with OpenTelemetry
logger.LogInformation(
    "Item checked out. {ProductId} {UserId}",
    "PROD-123", "USER-456",
    extra: new Dictionary<string, object>
    {
        // This special attribute tells the Azure Monitor exporter to create a custom event
        ["microsoft.custom_event.name"] = "CheckoutComplete"
    }
);

You can find more examples of this in the "Send custom events" section of the Microsoft Learn document titled Add and Modify OpenTelemetry in Application Insights.

4. Tracking Custom Metrics

While you can attach numeric values to custom events, if your primary goal is to aggregate a number over time (e.g., find the average queue size), you should use custom metrics. They are more efficiently processed and stored for this purpose.

The Application Insights SDK provides two main ways to do this:

1. TrackMetric(): A simple method to send a single metric value.
2. GetMetric().TrackValue(): The preferred, more advanced API. It pre-aggregates metrics on your application before sending them in batches, which is more efficient and cost-effective, especially for high-frequency metrics. It also supports creating multi-dimensional metrics.

The following video provides an excellent walkthrough of tracking both single-dimensional and multi-dimensional metrics and visualizing them in the Azure portal.

OpenTelemetry Equivalent

With OpenTelemetry, you use the System.Diagnostics.Metrics.Meter API, which is the .NET standard. You create instruments like Counter or Histogram, and the Azure Monitor exporter automatically maps them to custom metrics in Application Insights.

// OTel: Define a meter and a counter instrument
var meter = new Meter("MyApplication.BusinessMetrics");
var itemsSoldCounter = meter.CreateCounter<int>("items-sold");

// Later in the code, increment the counter with dimensions
itemsSoldCounter.Add(1, new KeyValuePair<string, object>("item_category", "electronics"));

You can review detailed code examples for this in the "Add custom metrics" section of the Add and Modify OpenTelemetry in Application Insights documentation.

5. Hands-On Practice

Now it's time to apply what you've learned. You will modify the .NET Web API project you worked on in the previous lesson to add custom telemetry. We will use the TelemetryClient approach as it makes the concepts of events and metrics very explicit.

Instructions:

1. Open Your Project: Open the .NET Web API project you instrumented in the previous lab.
2. Inject TelemetryClient: In your WeatherForecastController.cs, add a private field for TelemetryClient and inject it into the constructor.

   using Microsoft.ApplicationInsights; // Add this using statement
   // ...
   
   [ApiController]
   [Route("[controller]")]
   public class WeatherForecastController : ControllerBase
   {
       private static readonly string[] Summaries = new[] { /* ... */ };
       private readonly ILogger<WeatherForecastController> _logger;
       private readonly TelemetryClient _telemetryClient; // Add this field
   
       // Modify the constructor
       public WeatherForecastController(ILogger<WeatherForecastController> logger, TelemetryClient telemetryClient)
       {
           _logger = logger;
           _telemetryClient = telemetryClient; // Add this line
       }
   
       [HttpGet(Name = "GetWeatherForecast")]
       public IEnumerable<WeatherForecast> Get()
       {
           // ... controller logic
       }
   }
   

3. Track a Custom Event: Inside the Get() method, add a call to TrackEvent. This event will signify that a forecast was requested and will include the user agent as a custom property.

   [HttpGet(Name = "GetWeatherForecast")]
   public IEnumerable<WeatherForecast> Get()
   {
       // Track the custom event
       var eventProperties = new Dictionary<string, string>
       {
           { "UserAgent", Request.Headers["User-Agent"].ToString() }
       };
       _telemetryClient.TrackEvent("WeatherForecastRequested", eventProperties);
   
       return Enumerable.Range(1, 5).Select(index => new WeatherForecast
       {
           // ... existing code
       })
       .ToArray();
   }
   

4. Track a Custom Metric: Inside the same Get() method, let's track the number of forecast days being returned.

   [HttpGet(Name = "GetWeatherForecast")]
   public IEnumerable<WeatherForecast> Get()
   {
       // ... code for tracking the event ...
   
       // Track the custom metric
       _telemetryClient.TrackMetric("ForecastDays", 5);
   
       return Enumerable.Range(1, 5).Select(index => new WeatherForecast
       // ... existing code
   }
   

5. Run and Verify:
   • Run your application locally. Make sure your appsettings.json still has the connection string.
   • Use a browser or a tool like Postman to call the /weatherforecast endpoint several times.
   • Go to your Application Insights resource in the Azure portal.
   • Verify the event: Navigate to Usage > Events. After a few minutes, you should see "WeatherForecastRequested" in the list. Click on it to see samples and inspect the UserAgent custom property.
   • Verify the metric: Navigate to Monitoring > Metrics. In the metrics chart, select the Metric Namespace Custom (or Log-based metrics), then choose the Metric ForecastDays. You should see the data points you sent.

This hands-on exercise will take approximately 15 minutes.

Conclusion

In this lesson, you have gone beyond the default telemetry to instrument your application with meaningful, custom data.

Key Takeaways:

• Custom Events are for counting discrete occurrences (e.g., business actions).
• Custom Metrics are for tracking and aggregating numeric values over time.
• The TelemetryClient class, obtained via dependency injection, is the primary tool for sending custom telemetry with the Application Insights SDK.
• The TrackEvent method sends custom events, which can be enriched with properties (dimensions) and metrics (measurements).
• The TrackMetric and GetMetric methods send custom metrics, which can be viewed and aggregated in the Azure portal's Metrics Explorer.

Next Steps

Now that you are collecting both standard and custom telemetry, your Application Insights resource is filling up with valuable data. But how do you sift through it all to find the specific information you need? In our next lesson, we will introduce the Kusto Query Language (KQL), the powerful tool you will use to write foundational queries and analyze all the telemetry data you're collecting.