Collect diagnostics in containers
The same diagnostics tools that are useful for diagnosing .NET Core issues in other scenarios also work in Docker containers. However, some of the tools require special steps to work in a container. This article covers how tools for gathering performance traces and collecting dumps can be used in Docker containers.
Using .NET CLI tools in a container
These tools apply to: ✔️ .NET Core 3.1 SDK and later versions
The .NET Core global CLI diagnostic tools (dotnet-counters, dotnet-dump, dotnet-gcdump, dotnet-monitor, and dotnet-trace) are designed to work in a wide variety of environments and should all work directly in Docker containers. Because of this, these tools are the preferred method of collecting diagnostic information for .NET Core scenarios targeting .NET Core 3.1 or later in containers.
You can also install these tools without the .NET SDK by downloading the single-file variants from the links in the previous paragraph. These installs require a global install of the .NET runtime version 3.1 or later, which you can acquire following any of the prescribed methods in the .NET installation documentation or by consuming any of the official runtime containers.
Using .NET Core global CLI tools in a sidecar container
If you would like to use .NET Core global CLI diagnostic tools to diagnose processes in a different container, bear the following additional requirements in mind:
- The containers must share a process namespace (so that tools in the sidecar container can access processes in the target container).
- The .NET Core global CLI diagnostic tools need access to files the .NET Core runtime writes to the /tmp directory, so the /tmp directory must be shared between the target and sidecar container via a volume mount. This could be done, for example, by having the containers share a common volume or a Kubernetes emptyDir volume. If you attempt to use the diagnostic tools from a sidecar container without sharing the /tmp directory, you will get an error about the process "not running compatible .NET runtime."
PerfCollect in a container
This tool applies to: ✔️ .NET Core 2.1 and later versions
PerfCollect script is useful for collecting performance traces and is the recommended tool for collecting traces prior to .NET Core 3.0. If using
PerfCollect in a container, keep the following requirements in mind:
PerfCollectrequires some environment variables be set prior to the app it is profiling starting. These can be set either in a Dockerfile or when starting the container. Because these variables shouldn't be set in normal production environments, it's common to just add them when starting a container that will be profiled. The two variables that PerfCollect requires are:
When executing the app with .NET 7, you must also set
DOTNET_EnableWriteXorExecute=0 in addition to the preceding environment variables.
.NET 6 standardizes on the prefix
DOTNET_ instead of
COMPlus_ for environment variables that configure .NET run-time behavior. However, the
COMPlus_ prefix will continue to work. If you're using a previous version of the .NET runtime, you should still use the
COMPlus_ prefix for environment variables.
PerfCollect in a sidecar container
If you would like to run
PerfCollect in one container to profile a .NET Core process in a different container, the experience is almost the same except for these differences:
- The environment variables mentioned previously (
DOTNET_EnableEventLog) must be set for the target container (not the one running
- The container running
PerfCollectmust have the
SYS_ADMINcapability (not the target container).
- The two containers must share a process namespace.