Profiling in Docker container using port forwarding

In this article, we will demonstrate how to set up profiling for a .NET application running in a Docker container. The container will be configured so that the local port *:10001 is mapped to the port of the profiler agent running inside the Docker container. You will be able to connect the profiler UI to this port using the direct discovery method.

• Enable profiling in Linux Docker images
• Enable profiling in Windows Docker images
• Run Docker container
• Connect to the profiled application
• Collect profiler snapshots and logs
• Containers with restricted home directory

Enable profiling in Linux Docker images

1. Add a new stage to your Dockerfile. For example:

   FROM alpine as yourkit-stage
   RUN wget -q https://www.yourkit.com/dotnet-profiler/download/docker/YourKit-NetProfiler-2025.3-docker.zip
   RUN unzip -q YourKit-NetProfiler-2025.3-docker.zip

2. Copy profiler files and enable profiling in your image. For example:

   # Copy profiler files from the previous stage
   COPY --from=yourkit-stage /YourKit-NetProfiler /YourKit-NetProfiler
   
   # Enable profiling
   ENV CORECLR_ENABLE_PROFILING="1" \
       CORECLR_PROFILER="{E5A4ADC4-C749-400D-B066-6AC8C1D3790A}" \
       CORECLR_PROFILER_PATH_64="/YourKit-NetProfiler/bin/linux-x86-64/libynpagent.so" \
       YNP_STARTUP_OPTIONS="listen=all,port=10001"

   Please choose an appropriate agent path for your docker architecture. The path in the example above corresponds to Linux x64 (glibc), please replace it if your docker architecture differs.

   Platform		Agent path
   Linux (glibc)	x86, 64-bit	/YourKit-NetProfiler/bin/linux-x86-64/libynpagent.so
   	ARM 64-bit (AArch64)	/YourKit-NetProfiler/bin/linux-arm-64/libynpagent.so
   Alpine Linux (musl)	x86, 64-bit	/YourKit-NetProfiler/bin/linux-musl-x86-64/libynpagent.so
   	ARM 64-bit (AArch64)	/YourKit-NetProfiler/bin/linux-musl-arm-64/libynpagent.so

Enable profiling in Windows Docker images

1. Add a new stage to your Dockerfile to download YourKit .NET Profiler agents:

   FROM mcr.microsoft.com/windows/nanoserver:2004 as yourkit-stage
   RUN curl -fLOSs https://www.yourkit.com/dotnet-profiler/download/docker/YourKit-NetProfiler-2025.3-docker.zip
   RUN tar xf YourKit-NetProfiler-2025.3-docker.zip -C c:

2. Copy profiler files and enable profiling in your image. For example:

   # Copy profiler files from the previous stage
   COPY --from=yourkit-stage /YourKit-NetProfiler /YourKit-NetProfiler
   
   # Enable profiling
   ENV CORECLR_ENABLE_PROFILING="1" \
       CORECLR_PROFILER="{E5A4ADC4-C749-400D-B066-6AC8C1D3790A}" \
       CORECLR_PROFILER_PATH_32="C:\YourKit-NetProfiler\bin\windows-x86-32\ynpagent.dll" \
       CORECLR_PROFILER_PATH_64="C:\YourKit-NetProfiler\bin\windows-x86-64\ynpagent.dll" \
       CORECLR_PROFILER_PATH="C:\YourKit-NetProfiler\bin\windows-arm-64\ynpagent.dll" \
       COR_ENABLE_PROFILING="1" \
       COR_PROFILER="{E5A4ADC4-C749-400D-B066-6AC8C1D3790A}" \
       COR_PROFILER_PATH_32="C:\YourKit-NetProfiler\bin\windows-x86-32\ynpagent.dll" \
       COR_PROFILER_PATH_64="C:\YourKit-NetProfiler\bin\windows-x86-64\ynpagent.dll" \
       COR_PROFILER_PATH="C:\YourKit-NetProfiler\bin\windows-arm-64\ynpagent.dll" \
       YNP_STARTUP_OPTIONS="listen=all,port=10001"

Run Docker container

docker run -p 10001:10001 yourkit-demo

In our example, the agent is configured to listen port=10001. We use -p option to map port 10001 on the Docker host to TCP port 10001 in the container.

Connect to the profiled application

When the application is running in the container, connect to it from the profiler UI using the direct discovery method. You will need to specify IP address of your Docker container and 10001 as a port number. If you are running Docker locally on your developer machine, please use localhost as a container address.

Collect profiler snapshots and logs

If you cannot or do not wish to connect the profiler UI to the Docker container and prefer to automatically manage profiling and snapshot capturing instead, you may use the startup option dir to override the default snapshot directory. Map this directory in Docker using the -v flag and analyze the snapshots later.

Should you need the agent log file for troubleshooting purposes, map a host directory to the container and specify it with the startup option log_dir.

Containers with restricted home directory

For security reasons, the user home directory in a docker container may not exist or be read-only. In this case, the agent will use /tmp directory instead of <user home>/Snapshots as the default snapshot directory. The snapshot directory may be overridden with the startup option dir.

The profiler agent log file neither can be created in its normal location <user home>/.yjp/log. Should you need the agent log file for troubleshooting purposes, specify a writable directory for it with the startup option log_dir.

Complete example

• Dockerfile content:

  FROM alpine as yourkit-stage
  RUN wget -q https://www.yourkit.com/dotnet-profiler/download/docker/YourKit-NetProfiler-2025.3-docker.zip
  RUN unzip -q YourKit-NetProfiler-2025.3-docker.zip
  
  FROM mcr.microsoft.com/dotnet/samples:aspnetapp
  
  # Copy profiler files from the previous stage
  COPY --from=yourkit-stage /YourKit-NetProfiler /YourKit-NetProfiler
  
  # Enable profiling
  ENV CORECLR_ENABLE_PROFILING="1" \
      CORECLR_PROFILER="{E5A4ADC4-C749-400D-B066-6AC8C1D3790A}" \
      CORECLR_PROFILER_PATH_64="/YourKit-NetProfiler/bin/linux-x86-64/libynpagent.so" \
      YNP_STARTUP_OPTIONS="listen=all,log_dir=/logs,dir=/snapshots,sampling"

• Command line:

  mkdir -p $(pwd)/logs
  mkdir -p $(pwd)/snapshots
  docker build $(pwd) -t yourkit-demo
  docker run -p 10001-10010:10001-10010 -v $(pwd)/logs:/logs -v $(pwd)/snapshots:/snapshots yourkit-demo