Profiling in Docker container using YourKit Connection Broker

This article describes how to set up profiling of .NET application running in a Docker container.

We will use YourKit Connection Broker as a middleware, which helps to establish connection between profiler UI and the profiler agent running in a Docker container. This method has the following advantages over the direct connection:

• You do not need to know the IP address of your Docker container, and TCP port that the profiler agent is listening to.
• You do not need to publish profiler agent port to the outside world.
• You have an ability to configure access to the profiled application.

YourKit Connection Broker setup

This is a step-by-step instruction how to sign-up YourKit Connection Broker account. All preparations should not take more than 5 minutes. You need to create a security zone and access token to it.

In this example:

• The connection broker has https://cloud.yourkit.com address. The real broker address is the cloud region address of the security zone.
• The access token to the security zone is mytoken. The real token you have just created on the first YourKit Connection Broker setup step.

Enable profiling in Linux Docker images

• 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

• 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="broker_url=https://cloud.yourkit.com,broker_token=mytoken"

  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

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

  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:

• 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="broker_url=https://cloud.yourkit.com,broker_token=mytoken"

Run Docker container

Build and run the container for the modified Dockerfile, for example:

docker run my_container

Connect to the profiled application

When the application is running in the container, connect to it from the profiler UI using the YourKit Connection Broker discovery method. You will need to use the same broker address and access token, you have specified in the agent options.

Collect profiler snapshots and logs

If you can't or don't want to connect the profiler UI to the Docker container, and instead automatically control profiling and snapshot capturing, you may want to use the startup option dir to override default snapshot directory. Map this directory in Docker, for example with -v flag, and analyze 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.

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="broker_url=https://cloud.yourkit.com,broker_token=mytoken,log_dir=/logs,dir=/snapshots,sampling"

• Command line:

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