Heap dumps, thread dumps and application logs#

When a run shows a problem inside the application rather than in front of it, JMXPress can collect the evidence from a machine — if that machine has been set up to allow it.

This is off until somebody turns it on#

Careful Diagnostics are disabled on every agent by default, and are switched on in a file on that machine rather than from the web page. A heap dump is every object alive in the application at that instant — session tokens, connection strings, customer records — and an application log is whatever the application chose to write. Neither is something a server should be able to take from a machine because somebody clicked a button.

Enabling it on a machine#

Edit agent.ini on the computer itself and restart the agent:

[diagnostics]
enabled = yes
logs = C:\apps\checkout\logs, D:\tomcat\logs

enabled alone permits process listing, thread dumps and heap dumps of JVMs that agent's own user can attach to. That limit is the operating system's rule, not ours, which is why no path or credential is involved.
logs is separate and names the only directories a log may be read from. Without it, log collection is refused outright.

A request for a path outside those folders is refused on that machine, rather than being something the server promises not to ask for. So is a path that resolves outside them after links are followed — a junction or symbolic link planted inside an allowed folder does not get you out of it, and such a file is not even listed.

Collecting#

Utilities → Collect from a computer.

Choose a paired computer.
Choose what to collect: a process list, a thread dump, a heap dump, or a log file.
For a dump, pick the Java process from the list the agent reports.

Collection uses jcmd from the JDK on that machine — Thread.print for a thread dump, GC.heap_dump for a heap dump. A JRE is not enough; the machine needs a JDK.

What happens to what is collected#

It is stored on the server in a folder created with restrictive permissions, and each file is written restrictively too.
It is listed only to people in the organisation it belongs to.
It is removed after diagnostics_days (14 by default). Files left behind without a record — after an organisation is removed, say — are swept as well, because a heap dump on a disk nothing points at is every secret that was in that application.

Reading what you collected#

Page	Reads
Utilities → Thread Analysis	A thread dump: states, contention, deadlocks
Utilities → Heap Analysis	A heap dump: what is holding memory
Utilities → Memory Analysis	Memory behaviour over a run

You can also download what was collected.

Sizes and timeouts#

Limit	Value
Heap dump	512 MB
Log file	8 MB
Waiting for the agent to answer	15 minutes

A capture the agent never answers is timed out and marked failed, so the page does not show "waiting" for a machine that went away an hour ago.

If it is refused#

The agent says which of the two reasons applies, and both are fixed on that machine rather than on the server:

"Diagnostics are switched off on this computer" — add [diagnostics] enabled = yes to agent.ini and restart the agent.
"No log folders are allowed on this computer" — add [diagnostics] logs = <folder>.