Profiling in Docker container using port forwarding

In this article, we will demonstrate how to set up profiling for a Java 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.

• Configuring the Docker container
• Build Docker container
• Run Docker container
• Connect to the profiled application
• Collect profiler snapshots and logs
• Containers with restricted home directory

Configuring the Docker container

Add few lines to your Dockerfile:

1. Download YourKit Java Profiler agents:

   RUN wget https://www.yourkit.com/download/docker/YourKit-JavaProfiler-2025.3-docker.zip -P /tmp/ && \
     unzip /tmp/YourKit-JavaProfiler-2025.3-docker.zip -d /usr/local && \
     rm /tmp/YourKit-JavaProfiler-2025.3-docker.zip

2. Load the agent to the JVM by adding the Java command line option -agentpath.

   For example, if you start your application with

   java -jar my-app.jar

   ...do it like this:

   java -agentpath:/usr/local/YourKit-JavaProfiler-2025.3/bin/linux-x86-64/libyjpagent.so=port=10001,listen=all -jar my-app.jar

   In this example the agent is configured to listen port 10001, and profiler agent is a Linux 64-bit agent, compiled for glibc. If you run Docker on another platform, please choose the appropriate agent path from the table below. Here you can find the instructions for setting -agentpath, and comprehensive guide on startup option.

   Platform		Agent path
   Linux (glibc)	x86, 64-bit	/usr/local/YourKit-JavaProfiler-2025.3/bin/linux-x86-64/libyjpagent.so
   	ARM 64-bit (AArch64)	/usr/local/YourKit-JavaProfiler-2025.3/bin/linux-arm-64/libyjpagent.so
   	ppc64le, 64-bit, little-endian	/usr/local/YourKit-JavaProfiler-2025.3/bin/linux-ppc-64le/libyjpagent.so
   Alpine Linux (musl)	x86, 64-bit	/usr/local/YourKit-JavaProfiler-2025.3/bin/linux-musl-x86-64/libyjpagent.so
   	ARM 64-bit (AArch64)	/usr/local/YourKit-JavaProfiler-2025.3/bin/linux-musl-arm-64/libyjpagent.so
   Windows	x86, 64-bit	<profiler directory>\bin\windows-x86-64\yjpagent.dll
   	ARM 64-bit (AArch64)	<profiler directory>\bin\windows-arm-64\yjpagent.dll

Build Docker container

docker build -t yourkit-demo

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.