Skip to content

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 -javaagent option: the application's log has a line like [logaperture] LogAperture 1.0.0 active (WildFly) at startup.
  • Run logctl as the operating-system user the JVM runs as, on the same machine. logctl only sees JVMs it could attach to.
  • In a container, run logctl inside 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 -javaagent option.
  • 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 logger notes it, and --force sets it too;
  • the change hasn't already reverted: logctl status.

A rule doesn't act

  • logctl list rules shows the rule and its HITS. Zero hits means nothing has matched yet.
  • --below defaults to ERROR: an ERROR event isn't touched unless you give --below FATAL.
  • --throwable needs 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.
  • trim works 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:

  • top counts from when the agent started; right after startup there's little to show.
  • storms reports nothing while storm detection is off, which is the default. See Log storms.

A sticky change didn't come back after a restart

  • logctl env shows the state file. If its directory isn't writable by the JVM's user, LogAperture can't save changes: set -Dlogaperture.home to 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 sticky changes 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.