Work with several JVMs¶
logctl controls one JVM per command. This page covers how it picks that JVM.
How logctl finds the JVM¶
logctl looks for running JVMs that have the agent started, among those it is allowed to attach to:
on the same machine, run by the same operating-system user.
- Exactly one: it uses that one. Nothing to do.
-
None: it says so and exits with code 3:
No LogAperture-enabled JVM found. Start the application with -javaagent:logaperture-agent.jar.Check that the JVM was started with the agent, and that you are the user it runs as.
-
Several: on a terminal, it lists them as a numbered list to pick from. In a script, or with
--jsonor--yes, it can't ask. It prints the same list and exits with code 4:PID VERSION STARTED DIRECTORY COMMAND 28337 1.0.0 2026-10-15 20:45 /srv/app-a org.logaperture.agent.it.FixtureApp 28342 1.0.0 2026-10-15 20:45 /srv/app-b org.logaperture.agent.it.FixtureApp Several candidates — pass --pid <n>.
Choosing one¶
Pass the process id:
logctl --pid 28337 status
The list shows each JVM's directory and main class to tell them apart. jps -l lists Java
processes too.
When attaching is refused¶
Can't attach to PID 1 — run as the user that owns that process, or as root.
Exit code 5. Run logctl as the user the JVM runs as, for example with sudo -u jboss logctl ….
On Windows the message says to open the command prompt as Administrator, or to run as the account that owns the process. See Use logctl with a Windows service.
Two applications from one directory¶
Each JVM keeps its sticky changes in its own state file, named after the directory it was started
from. Two JVMs started from the same directory can't share one: the second to start can't keep
sticky changes, and says so in its log. Give each its own name with
-Dlogaperture.instanceId=<name>. See Agent options.