Profiling in Docker container using YourKit Connection Broker

This article describes how to set up profiling of Java 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.

Let's assume that after setting up a broker, the broker address is https://cloud.yourkit.com, and access token is mytoken.

On Docker side

1. Add few lines to your Dockerfile:

• Install 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

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

  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.

  • Profiler agent is a Linux 64-bit agent, compiled for glibc. If you run Docker on another platform, please choose appropriate agent path from the table below:

    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

    Please find detailed description of how to specify -agentpath and choose the agent startup options here.

2. Build and run the container for the modified Dockerfile.

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.

Notes on a special case: a container 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 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.