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."
Using PerfCollect
in a container
This tool applies to: ✔️ .NET Core 2.1 and later versions
The 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:
PerfCollect
requires theSYS_ADMIN
capability (in order to run theperf
tool), so be sure the container is started with that capability.PerfCollect
requires 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:DOTNET_PerfMapEnabled=1
DOTNET_EnableEventLog=1
Note
When executing the app with .NET 7, you must also set DOTNET_EnableWriteXorExecute=0
in addition to the preceding environment variables.
Note
.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.
Using 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_PerfMapEnabled
andDOTNET_EnableEventLog
) must be set for the target container (not the one runningPerfCollect
). - The container running
PerfCollect
must have theSYS_ADMIN
capability (not the target container). - The two containers must share a process namespace.
Feedback
Submit and view feedback for