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 Docker images

• Download the correct version of YourKit .NET Profiler agent. In this example, the profiler agent is a Linux 64-bit agent, compiled for glibc:

  ADD https://www.yourkit.com/dl/agents/linux-x86-64/libynpagent.so?product=ynp&version=2026.3 /usr/local/lib/

  Use the agent URL for your Docker architecture from the table below:

  Platform		Agent URL
  Linux (glibc)	x86, 64-bit	https://www.yourkit.com/dl/agents/linux-x86-64/libynpagent.so?product=ynp&version=2026.3
  	ARM 64-bit (AArch64)	https://www.yourkit.com/dl/agents/linux-arm-64/libynpagent.so?product=ynp&version=2026.3
  Alpine Linux (musl)	x86, 64-bit	https://www.yourkit.com/dl/agents/linux-musl-x86-64/libynpagent.so?product=ynp&version=2026.3
  	ARM 64-bit (AArch64)	https://www.yourkit.com/dl/agents/linux-musl-arm-64/libynpagent.so?product=ynp&version=2026.3
  Windows	x86, 64-bit	https://www.yourkit.com/dl/agents/windows-x86-64/ynpagent.dll?product=ynp&version=2026.3
  	ARM 64-bit (AArch64)	https://www.yourkit.com/dl/agents/windows-arm-64/ynpagent.dll?product=ynp&version=2026.3

• Enable profiling in your Dockerfile. For example:

  ENV CORECLR_ENABLE_PROFILING="1" \
      CORECLR_PROFILER="{E5A4ADC4-C749-400D-B066-6AC8C1D3790A}" \
      CORECLR_PROFILER_PATH="/usr/local/lib/libynpagent.so" \
      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 mcr.microsoft.com/dotnet/sdk
  
  # Download profiler agent
  ADD https://www.yourkit.com/dl/agents/linux-x86-64/libynpagent.so?product=ynp&version=2026.3 /usr/local/lib/
  
  # Enable profiling
  ENV CORECLR_ENABLE_PROFILING="1" \
      CORECLR_PROFILER="{E5A4ADC4-C749-400D-B066-6AC8C1D3790A}" \
      CORECLR_PROFILER_PATH="/usr/local/lib/libynpagent.so" \
      YNP_STARTUP_OPTIONS="broker_url=https://cloud.yourkit.com,broker_token=mytoken,log_dir=/logs,dir=/snapshots,cpu=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