Breadcrumbs

Debug Mode

Overview

From IM 8.0 you can run a provisioned IM instance in debug mode. The instance JVM opens a remote-debug (JDWP) port, and you attach your IDE debugger to the running instance — set breakpoints in your custom Groovy classes and step through your integration while it processes real data.

The instance starts and runs normally with debug mode on (suspend=n) — nothing waits for a debugger to connect.

How to activate it

Debug mode is not available in Platform Manager yet (Platform Manager support is planned). Today the flag is set manually in the internal deployment configuration of the instance.

Each cluster has a deployment state repository under https://gitlab.pricefx.eu/dev-ops/infra (for example im-gdev-1-europe-west1_app_clusters). Every instance is one file, instances/<instance-name>.json, and debug mode is one flag in it:

JSON
"behavior": {
  "debugModeEnabled": true
}

You normally do not have access to these repositories — ask CloudOps (or the IM team) to set the flag for your instance. After the flag is committed, the instance redeploys automatically and starts with the debug port open. Setting the flag back to false redeploys again and closes the port.

What debug mode does

With the flag on, the instance JVM starts with the standard Java debug agent:

-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005

  • Port 5005 is opened in the instance deployment and exposed on the standard instance hostname — the same host you use to reach the instance.

  • suspend=n — the instance does not wait for a debugger; it starts and processes integrations normally.

  • Everything else about the instance is unchanged.

Connect your IDE

No port-forwarding is needed. With debug mode on, port 5005 is opened in the deployment and available on the standard hostname of the instance — the same host you use for the instance API (for example pim-example-qa.<domain>).

Attach with a standard remote-debug configuration against <instance-host>:5005:

  • IntelliJ IDEA: Run → Edit Configurations → + → Remote JVM Debug. Keep the defaults (Attach to remote JVM, transport Socket), set host <instance-host> and port 5005, then start it with Debug.

  • VS Code: add a java launch configuration with "request": "attach", "hostName": "<instance-host>", "port": 5005.

  • Eclipse: Run → Debug Configurations → Remote Java Application, connection type Standard (Socket Attach), host <instance-host>, port 5005.

Open your integration project (the same code that is deployed on the instance) in the IDE, set breakpoints in your Groovy classes or processors, and trigger the route — the debugger stops at your breakpoint.

Rules and caveats

  • Turning debug mode on or off redeploys the instance — in-flight integrations are interrupted the same way as on any redeploy.

  • Turn debug mode off when you finish. A permanently open debug port is an unnecessary risk and a small performance cost.

  • A hit breakpoint pauses the route thread. When you pause too long, timeouts and health checks can trigger — resume promptly, or keep debug sessions short.

  • To debug startup logic, attach quickly after the pod starts (suspend=n means the JVM does not wait), or use a breakpoint in code that runs repeatedly.