What diagnostic tools are available in .NET Core?
Software doesn't always behave as you would expect, but .NET Core has tools and APIs that will help you diagnose these issues quickly and effectively.
This article helps you find the various tools you need.
Managed debuggers
Managed debuggers allow you to interact with your program. Pausing, incrementally executing, examining, and resuming gives you insight into the behavior of your code. A debugger is the first choice for diagnosing functional problems that can be easily reproduced.
Logging and tracing
Logging and tracing are related techniques. They refer to instrumenting code to create log files. The files record the details of what a program does. These details can be used to diagnose the most complex problems. When combined with time stamps, these techniques are also valuable in performance investigations.
Metrics
EventCounters allows you to write metrics to identify and monitor performance issues. Metrics incur lower performance overhead compared to tracing, making it more suitable for an always-on performance monitoring. The .NET runtime and libraries publish several well-known EventCounters that you can monitor as well.
Unit testing
Unit testing is a key component of continuous integration and deployment of high-quality software. Unit tests are designed to give you an early warning when you break something.
Dumps
A dump is a file that contains a snapshot of the process at the time of creation. These can be useful for examining the state of your application for debugging purposes.
Symbols
Symbols are a fundamental requirement for debugging and other diagnostic tools. The contents of symbol files vary between languages, compilers, and platforms. At a very high level symbols are a mapping between the source code and the binary produced by the compiler. These mappings are used to provide things like line number information and names of your local variables in diagnostics tools such as Visual Studio and Visual Studio Code. The following link contains a detailed explanation of symbols for Windows, although many of the concepts apply to other platforms as well. .NET portable symbols have a "PDB" file extension similar to Windows PDB, though are not compatible with the Windows PDB format.
Collect diagnostics in containers
The same diagnostics tools that are used in non-containerized Linux environments can also be used to collect diagnostics in containers. There are just a few usage changes needed to make sure the tools work in a Docker container.
.NET Core diagnostic global tools
dotnet-counters
dotnet-counters is a performance monitoring tool for first-level health monitoring and performance investigation. It observes performance counter values published via the EventCounter API. For example, you can quickly monitor things like the CPU usage or the rate of exceptions being thrown in your .NET Core application.
dotnet-dump
The dotnet-dump tool is a way to collect and analyze Windows and Linux core dumps without a native debugger.
dotnet-gcdump
The dotnet-gcdump tool is a way to collect GC (Garbage Collector) dumps of live .NET processes.
dotnet-trace
.NET Core includes what is called the EventPipe through which diagnostics data is exposed. The dotnet-trace tool allows you to consume interesting profiling data from your app that can help in scenarios where you need to root cause apps running slow.
dotnet-symbol
dotnet-symbol downloads files (symbols, DAC/DBI, host files, etc.) needed to open a core dump or minidump. Use this tool if you need symbols and modules to debug a dump file captured on a different machine.
dotnet-sos
dotnet-sos installs the SOS debugging extension on Linux and macOS (and on Windows if you're using Windbg/cdb).
PerfCollect
PerfCollect is a bash script you can use to collect traces with perf and LTTng for a more in-depth performance analysis of .NET apps running on Linux distributions.
.NET Core diagnostics tutorials
Debug a memory leak
Tutorial: Debug a memory leak walks through finding a memory leak. The dotnet-counters tool is used to confirm the leak and the dotnet-dump tool is used to diagnose the leak.
Debug high CPU usage
Tutorial: Debug high CPU usage walks you through investigating high CPU usage. It uses the dotnet-counters tool to confirm the high CPU usage. It then walks you through using Trace for performance analysis utility (dotnet-trace) or Linux perf to collect and view CPU usage profile.
Debug deadlock
Tutorial: Debug deadlock shows you how to use the dotnet-dump tool to investigate threads and locks.
Debug a StackOverflow
Tutorial: Debug a StackOverflow demonstrates how to debug a StackOverflowException on Linux.
Debug Linux dumps
Debug Linux dumps explains how to collect and analyze dumps on Linux.
Measure performance using EventCounters
Tutorial: Measure performance using EventCounters in .NET shows you how to use the EventCounter API to measure performance in your .NET app.