---

✅ dotnet-counters – Command Reference (Explained Simply)

When you run:

dotnet-counters -h

You see 4 main commands:

Commands:
  monitor   Start monitoring a .NET application
  collect   Monitor counters in a .NET application and export the result into a file
  list      Display a list of counter names and descriptions, grouped by provider.
  ps        Lists the dotnet processes that can be monitored.
Code language: CSS (css)

Below is a simple explanation for each.

---

🟦 1. dotnet-counters monitor

Real-time monitoring (LIVE metrics)

This command shows metrics live in the terminal.

Example:

dotnet-counters monitor --process-id 1234 System.Runtime Microsoft.AspNetCore.Hosting
Code language: CSS (css)

Use when:

• You want to diagnose CPU spikes
• You want to monitor GC, ThreadPool, HTTP requests, EF load
• You need instant insights

---

🟧 2. dotnet-counters collect

Record metrics into a file (for later analysis)

Example:

dotnet-counters collect --process-id 1234 -o metrics.json
Code language: CSS (css)

Use when:

• You want offline analysis
• You want to attach the file to Jira/Slack
• You want long-running capture for production

The output can be consumed by:

• PerfView
• VS Diagnostic tools
• Custom dashboards

---

🟩 3. dotnet-counters list

Lists ALL available counters grouped by provider

Example:

dotnet-counters list
Code language: PHP (php)

It shows providers such as:

• System.Runtime
• Microsoft.AspNetCore.Hosting
• Microsoft.EntityFrameworkCore
• Microsoft.AspNetCore.Http.Connections
• Grpc.AspNetCore.Server
• Custom counters you create

Use when:

• You want to know which counters exist
• You want to pick the right providers for monitoring

---

🟪 4. dotnet-counters ps

Shows all .NET processes which can be monitored

Example:

dotnet-counters ps

Output:

1234  Orders.Api
5678  WorkerService1
Code language: CSS (css)

Use when:

• You don’t know the PID
• You want to confirm your app is running
• You want to attach to the correct process

---

📝 Slide-Ready Summary

dotnet-counters – Core Commands

Command	What It Does	When to Use
monitor	Shows live runtime metrics in console	Realtime troubleshooting
collect	Records metrics to a file	Post-analysis / long runs
list	Shows all available counters	Discover providers/counters
ps	Lists .NET processes	To find PID to attach

---

---

Master Table: Important dotnet-counters Metrics (with Explanations & Why They Matter)

---

1️⃣ System.Runtime — Core CLR Runtime Metrics

Metric	What It Means	Why It’s Important for Performance
CPU Usage (%)	CPU percentage used by the .NET process	Detects CPU bottlenecks; helps identify CPU-bound workloads, infinite loops, bad parallelism, or excessive processing.
Allocation Rate (B/sec)	How fast your app allocates managed memory	High allocation rate → frequent GC → latency spikes. Crucial for diagnosing app churn, LINQ inefficiencies, and memory-heavy code.
GC Heap Size (MB)	Total memory currently used by the managed heap	Detects memory leaks, memory growth over time, and inefficient caching patterns.
GC Committed Bytes (MB)	Memory reserved by GC from OS	Helps understand total memory pressure; correlates with working set expansion.
% Time in GC	Percentage of time spent in garbage collection	High value = app is frequently pausing; leads to latency issues and poor throughput.
Time paused by GC (ms/sec)	Actual stop-the-world pause time	High pause time directly causes slow API responses and jitter.
Gen 0/1/2 GC Count	Number of collections happening per second	High Gen0 = object churn. High Gen2 = severe performance issue because Gen2 GCs are expensive.
Gen 0/1/2 Size	Total bytes in each generation	Helps identify long-lived allocations, memory retention, and leaks.
LOH Size (Large Object Heap)	Memory used by objects ≥85 KB	LOH fragments memory; too big LOH increases GC cost. Critical for APIs that allocate large arrays/JSON blobs.
POH Size (Pinned Object Heap)	Memory that GC cannot move	High POH = higher fragmentation + potential leaks. Important for interop-heavy systems.
ThreadPool Thread Count	Number of active worker threads	Too low → starvation. Too high → excessive context switching.
ThreadPool Queue Length	Work items waiting for a thread	If >0 consistently → request queuing → latency spikes.
ThreadPool Completed Work Items/sec	Work throughput	Helps measure workload intensity and server utilization.
Lock Contention Count/sec	Threads waiting to enter locks	Indicates concurrency bottlenecks causing hangs and slowdowns.
Exception Count/sec	Exceptions thrown each second	High exceptions degrade performance due to stack walking + GC pressure.
Working Set (MB)	Total memory used by the process	High working set may cause swapping or OOM kills in containers.
IL Bytes Jitted / Methods Jitted	Total methods compiled by JIT	High values over time = JIT warmup not complete; affects startup latency.
Active Timers	Number of active timer callbacks	Too many timers → excessive scheduling overhead.

---

2️⃣ Microsoft.AspNetCore.Hosting — Request & Application Metrics

Metric	What It Means	Why It Matters
Requests/sec	Incoming requests throughput	Measures system load; used to detect saturation and capacity.
Current Requests	In-flight HTTP requests	High values = backpressure or slow request handlers.
Total Requests	Cumulative number of served requests	Useful for verifying app activity during load tests.
Failed Requests	Number of failed requests	Identifies reliability/stability issues.
Request Queue Length	Pending incoming requests	Queue > 0 → server not keeping up → potential cascading failure.

---

3️⃣ Microsoft-AspNetCore-Server-Kestrel — Server-Level Metrics

Metric	Meaning	Why It Matters
Current Connections	Active TCP connections	Detects overload, DDoS-like patterns, or connection leaks.
Connection Queue Length	Pending connections before they’re accepted	High queue = server saturation.
TLS Handshake Failures	Failed SSL handshakes	Indicates certificate issues or client misconfigurations.
Request Queue Length	HTTP requests waiting to be processed	Early warning sign of API latency under load.
Connections/sec	New incoming connections/second	High churn can cause CPU spikes and port exhaustion.

---

4️⃣ Microsoft.AspNetCore.Http.Connections — SignalR & WebSockets

Metric	Meaning	Why It Matters
Current Connections	Active WebSocket/SignalR connections	Helps size the real-time workload.
Connections Started	New connections opened	High rate = scaling pressure on real-time hubs.
Connections Stopped	Closed connections	Sharp increases indicate instabilities.
Connections Timed Out	Connections dropped unexpectedly	Indicates networking or idle-time issues.
Connection Duration	Avg time connections remain open	Useful for capacity planning.

---

5️⃣ System.Net.Http — Outbound HTTP Client Metrics

Metric	Meaning	Why It Matters
Requests Started/sec	Outbound calls initiated	Helps measure dependency load.
Requests Failed/sec	Outbound failures	Useful for detecting flaky downstream services.
Current HTTP/1.1 Connections	Active pooled connections	Helps identify connection pool exhaustion.
HTTP/2 Streams	Streams in use	Critical for gRPC or HTTP/2 workloads.
DNS Lookup Duration	Time taken for DNS resolution	Slow DNS = global latency issues.
Sockets Queued	Pending socket requests	Too many ⇒ networking bottleneck.

---

6️⃣ Microsoft.EntityFrameworkCore — Database & Query Performance

Metric	Meaning	Why It’s Critical
Queries Executed/sec	Database query rate	Detects DB overload & slow query patterns.
Active DbContexts	Number of active EF contexts	High values = context leaks or too many parallel queries.
Command Execution Count	DB commands executed	Measures DB workload intensity.
Optimistic Concurrency Failures	Version conflicts	Indicates concurrency problems & row contention.
Queries Compilation Events	EF query compilation	High compilation rate = missing compiled query reuse → performance loss.

---

7️⃣ Additional Important Diagnostic Signals

Metric	Meaning	Why It’s Useful
GC Fragmentation %	How fragmented the heap is	Fragmentation increases GC time & reduces memory efficiency.
GC Budget	Target allocation for next GC	Helps understand upcoming GC cycles.
JIT Time (ms/sec)	Time spent JIT-compiling code	Affects startup and “warm-up” performance.
Assemblies Loaded	Number of loaded assemblies	Too many → high memory + startup time.

---

🎯 Summary: Why These Metrics Matter

This table covers all critical metrics for diagnosing:

• High CPU
• Memory leaks
• High GC pressure
• Large object allocations
• ThreadPool starvation
• Lock contention
• Slow database queries
• HTTP failures & timeouts
• Real-time connection pressure
• Throughput & latency degradation
• Container OOM kills
• Cold-start & JIT issues

dotnet-counters is the first tool you should use during:

• Load Testing
• Performance Engineering
• CPU/Memory profiling
• Cloud production incidents
• GC or memory leak investigations

---