If you've been using EventCounters for instrumenting your .NET applications, it's time to consider migrating to the newer System.Diagnostics.Metrics API. Based on the OpenTelemetry specification, the Metrics API offers a more modern, flexible, and standardized approach to application instrumentation.
Why migrate?
The Metrics API provides several advantages over EventCounters:
- Industry Standard: Built on OpenTelemetry, ensuring compatibility with a wide ecosystem of monitoring tools
- Better Performance: More efficient with lower overhead
- Richer Functionality: Support for histograms, exemplars, and more sophisticated metric types
- Improved API Design: Cleaner, more intuitive interface for defining and recording metrics
- Better Tooling Support: Growing ecosystem support from APM vendors and monitoring solutions
Microsoft has indicated that EventCounters are in maintenance mode, with new development focused on the Metrics API.
So reasons enough to migrate our EventCounters to the new Metrics API. Let's go for it!
Our original EventCounters example
With EventCounters, you typically created an EventSource and used specialized counter types:
Migration guide
Step 1: Add the required package
While System.Diagnostics.Metrics is part of .NET 6+, you may want to add OpenTelemetry packages for collection:
dotnet add package OpenTelemetry.Exporter.Console
dotnet add package OpenTelemetry.Extensions.Hosting
Step 2: Create a meter
Replace your EventSource with a Meter. The meter name should follow reverse domain name notation:
Step 3: Map counter types
Here's how EventCounter types map to Metrics API instruments:
| Event Counter type | Metrics API equivalent | Use case |
| Event Counter | Counter<T> | Monotonically increasing values (requests, errors) |
| PollingCounter | ObservableGauge<T> | Current value snapshots (queue length, active connections) |
| IncrementingEventCounter | Counter<T> | Cumulative totals |
| IncrementingPollingCounter | ObservableCounter<T> | Cumulative totals from callbacks |
Step 4: Migrate counter definitions
Now we move the different event counter types over:
Step 5(optional): Add tags
One powerful feature of the Metrics API is built-in support for tags. This allows you to give extra context to a metric:
Remark: You can further improve the performance of tags by using the built-in source generators.
Step 6: Configure ServiceCollection
In your application startup inside Program.cs for ASP.NET Core add the following configuration:
Final result
Here is how the complete class looks like after the migration:
More information
Source-generated metrics with strongly-typed tags - .NET | Microsoft Learn
Understanding different metric APIs - .NET | Microsoft Learn