Troubleshooting¶
logctl can't find the JVM¶
No LogAperture-enabled JVM found. Start the application with -javaagent:logaperture-agent.jar.
- Check the JVM was started with the
-javaagentoption: the application's log has a line like[logaperture] LogAperture 1.0.0 active (WildFly)at startup. - Run
logctlas the operating-system user the JVM runs as, on the same machine.logctlonly sees JVMs it could attach to. - In a container, run
logctlinside the same container. - On Windows, if the application runs as a service, open the command prompt as Administrator. See Use logctl with a Windows service.
See Work with several JVMs for "Several candidates" and attach errors.
logctl needs a JDK¶
logctl uses the JVM attach mechanism, which only a JDK has. Run it with a JDK, not just a JRE. The
application itself can run on either.
The server won't start with the agent¶
Add -Dlogaperture.disabled=true to the JVM options and start again. The agent then does nothing.
- If the server starts, LogAperture is involved. Please
open an issue with the server log,
java -version, and every-javaagentoption. - If it still fails, the problem is elsewhere.
On WildFly, the log line The LogManager was not properly installed means the JVM's logging was
set up before WildFly's: check JAVA_OPTS for other agents or logging options.
A raised level shows nothing¶
Usually a handler is at a stricter level than the logger. The default handler (usually the console)
follows the change on its own; for any other handler, or one you set yourself, set logger warns
about it, with the command that fixes it. See
Raise a log level.
Also check:
- the logger's name is right:
logctl list loggers '*.<last part>' --show-all(see Find a logger); - a logger under it doesn't have a level of its own:
set loggernotes it, and--forcesets it too; - the change hasn't already reverted:
logctl status.
A rule doesn't act¶
logctl list rulesshows the rule and itsHITS. Zero hits means nothing has matched yet.--belowdefaults toERROR: anERRORevent isn't touched unless you give--below FATAL.--throwableneeds the exact class, not a parent class.- Events logged before LogAperture started, for example by another agent at startup, are out of reach. See Agent order.
trimworks on text log formats only in 1.0. A JSON or XML formatter writes the full trace.- Rules don't work on a plain JVM with Logback in 1.0.
top, doctor or storms report nothing¶
On a plain JVM with Logback they aren't available in 1.0. On WildFly:
topcounts from when the agent started; right after startup there's little to show.stormsreports nothing while storm detection is off, which is the default. See Log storms.
A sticky change didn't come back after a restart¶
logctl envshows the state file. If its directory isn't writable by the JVM's user, LogAperture can't save changes: set-Dlogaperture.hometo a writable directory. This is common in containers.- Two JVMs started from the same directory share a state file name; the second can't keep
stickychanges and says so in its log. Set-Dlogaperture.instanceId.
The vendor defaults file isn't applied¶
Run logctl doctor. If the file has an error, none of it applies, and vendor-defaults.file lists
every error with its line number. See Doctor checks.
logctl output shows - where the guide shows —¶
logctl prints — for "no value", and → and … in some messages. A console that can't show
them, such as Windows cmd with its default code page, gets -, -> and ... instead. Nothing
is missing; it's the same output. To see the originals in cmd with JDK 18 or later, switch the console to UTF-8 with
chcp 65001 before running logctl.
Seeing more of what LogAperture does¶
LogAperture writes one line at startup, then only warnings and errors. For more, start the JVM with
-Dlogaperture.diagnostics.level=INFO, or DEBUG. LogAperture's lines start with [logaperture].
Reporting a problem¶
For a question, or to tell us how a try-out went, use Discussions. For a bug, open an issue with:
- the output of
logctl env, which is written to be pasted into a bug report; - the command you ran and its output;
- any
[logaperture]lines from the application's log.