Docker Profiling

Pro Feature

Docker profiling requires a Pro license.

Profile Java applications running in local Docker containers with automatic discovery.

How It Works

GalataJ automatically discovers Java applications running inside Docker containers on your local machine.

Start your Docker container with a Java application
Open the Profiler panel in your IDE
Click Refresh — Docker containers appear in the JVM list
Select the container and start profiling

No configuration needed. GalataJ handles the connection automatically.

JDK recommended for automatic attach

If your container uses a JDK image, GalataJ attaches automatically with zero configuration. If your container uses a JRE or a JDK without attach support, you can still profile using the -javaagent approach. See Alternative: Using -javaagent below.

What Gets Discovered

GalataJ finds Java processes running in:

Docker Desktop (Windows/macOS)
Docker Engine (Linux)
Docker Compose projects

As long as the container is running on your local machine, GalataJ can profile it.

Identifying Containers

In the JVM list, Docker containers show:

Container name — The name you gave the container
Image name — The Docker image being used
Container ID — Short ID for identification

Alternative: Using -javaagent

If automatic attach doesn’t work — for example, your container uses a JRE image or a JDK that doesn’t support runtime attach — you can load the profiler agent at startup using -javaagent. This works with any Java image, including JRE.

Choose one of the following options:

Option 1: docker-compose.yml

Add the following to your service definition — no Dockerfile changes needed:

services:
  my-app:
    # ... your existing config ...
    volumes:
      - ~/.galataj/agent/agent.jar:/opt/galataj-agent.jar:ro
    environment:
      - JAVA_TOOL_OPTIONS=-javaagent:/opt/galataj-agent.jar
      - GALATAJ_PACKAGE=com.mycompany.myapp
    extra_hosts:
      - "host.docker.internal:host-gateway"

Then restart your services:

docker compose up

Option 2: Dockerfile

Copy the agent JAR into your project directory:

cp ~/.galataj/agent/agent.jar ./agent.jar

Then add these lines to your Dockerfile before the ENTRYPOINT:

COPY agent.jar /opt/galataj-agent.jar
ENV JAVA_TOOL_OPTIONS="-javaagent:/opt/galataj-agent.jar"
ENV GALATAJ_PACKAGE=com.mycompany.myapp

Option 3: docker run

No file changes needed — pass volume mount and environment flags directly:

docker run \
  -v ~/.galataj/agent/agent.jar:/opt/galataj-agent.jar:ro \
  -e JAVA_TOOL_OPTIONS="-javaagent:/opt/galataj-agent.jar" \
  -e GALATAJ_PACKAGE=com.mycompany.myapp \
  --add-host=host.docker.internal:host-gateway \
  your-image

Important Notes

Replace com.mycompany.myapp with your application’s base package (e.g., the package containing your @SpringBootApplication class).
On Linux, the extra_hosts (Compose) or --add-host (docker run) flag is required so the container can reach the host. The examples above already include this.
When using the IDE wizard, the generated snippet already has the correct package filled in.

Limitations

Local Only

GalataJ can only profile Docker containers running on your local machine. Remote Docker hosts (SSH, remote Docker API) are not currently supported.

Troubleshooting

Container not appearing

Make sure the container is running (not stopped)
Click Refresh in the profiler panel
Verify the container has a Java process inside
Run Health Check to ensure GalataJ is working

Profiling not starting

Make sure you have a Pro license activated
Check that Docker is running on your machine
Try restarting your IDE

Attach failed: jdk.attach not available

If you see errors like:

“jdk.attach module not available in container”
“The container image must include JDK (not just JRE)”
“NoClassDefFoundError: com/sun/tools/attach/AttachNotSupportedException”

the container is using a JRE image or a JDK without attach support.

Solution A — Switch to a JDK image:

# Before (fails for automatic attach)
FROM eclipse-temurin:17-jre

# After (works with GalataJ)
FROM eclipse-temurin:17-jdk

Recommended JDK images: eclipse-temurin:17-jdk, amazoncorretto:17, azul/zulu-openjdk:17.

Rebuild the image and run the container again, then start profiling.

Solution B — Use -javaagent instead:

If you can’t switch to a JDK image, use the -javaagent approach which works with any Java image including JRE. See Alternative: Using -javaagent above.

Next Steps

Upgrade to Pro

Get Docker profiling and more

Upgrade →

Session History

Compare container performance over time

Learn more →