Skip to content

Raise a log level

For more detail from part of an application for a while, then back to normal.

Above: an application's checkout logger at DEBUG for 30 seconds on WildFly, with the console in the top pane. The change reverts on its own, and the console's AUTO level goes back with it.

The output on this page is from WildFly 26.1.3.

One logger

logctl set logger io.undertow.request DEBUG for 5m
io.undertow.request → DEBUG   (FOR, reverts 05:45:49 local — in 4m)
handler CONSOLE → AUTO, currently DEBUG   (follows io.undertow.request)

The second line is the console following the change: see The console follows.

The level is one of TRACE, DEBUG, INFO, WARN, ERROR, OFF or ALL. The tier at the end says how long the change lasts: for 30m, session (until the JVM stops), or sticky (until you reset it). Without a tier, for 4h. See Tiers and expiry.

Add --reason to say why; it shows in status and goes in the audit trail:

logctl set logger io.undertow.request DEBUG for 30m --reason "INC-4211 slow requests"

If you don't know the logger's full name, see Find a logger.

A logger and everything under it

Setting a logger sets every logger under it too, now and later, because they inherit its level:

logctl set logger org.jboss.as TRACE for 5m

The exception is a logger under it that has a level of its own in the application's configuration. It keeps that level, and logctl says so:

org.jboss.as → TRACE   (FOR, reverts 01:31:58 local — in 4m)
NOTE: 1 logger under org.jboss.as keeps its own level and won't follow TRACE: org.jboss.as.config (DEBUG).
  To set it too: logctl set logger org.jboss.as TRACE for 5m --force

--force sets those too:

org.jboss.as → TRACE   (FOR, reverts 01:31:58 local — in 4m)
org.jboss.as.config → TRACE   (FOR, reverts 01:31:58 local — in 4m, forced)

and resetting the parent puts them back with it:

logctl reset logger org.jboss.as
org.jboss.as → INFO (baseline)
org.jboss.as.config → DEBUG (baseline)   (forced by org.jboss.as)

A pattern ending in * ('org.jboss.as.*') is refused for set: name the parent instead.

Every logger matching a name

A log line often shows only the last part of a logger's name. A pattern starting with * sets every logger whose name ends that way:

logctl set logger '*.Worker' DEBUG for 10m

On a terminal, logctl lists the matching loggers to pick from. In a script, add --yes to take all of them:

logctl set logger '*.Worker' DEBUG for 10m --yes
org.logaperture.sample.work.Worker → DEBUG   (FOR, reverts 01:36:56 local — in 9m)

The pattern is applied once, to the loggers that exist now. A matching logger created later isn't changed. Quote the pattern, so the shell doesn't expand the *.

The console follows

A logger's level decides what is logged. Each handler (the console, a file) has a level of its own that decides what it writes. WildFly's console handler is usually at INFO, so on its own it would write DEBUG lines to server.log but not to the console.

The console is the default handler (DEFAULT_HANDLERS), so set logger brings it along: a default handler that would drop the new records goes to AUTO, where it tracks the most verbose change you have active. It goes back to its own level when the changes it follows have all ended: expired, reset, or set back to a quieter level. logctl status shows what it follows:

HANDLER  LEVEL  MODE  TIER  REVERTS          REASON
CONSOLE  DEBUG  AUTO  FOR   with the logger  follows io.undertow.request

A handler you've set yourself is left as you set it. If your setting lets the records through for at least as long as the logger change, nothing changes. If it ends sooner, the handler keeps your setting until then and follows the change after that. If it blocks them, set logger warns about it.

To change only the logger, add --keep-handlers: it keeps the handlers at their own levels instead of letting them follow the change. To make that the rule for a whole server, start its JVM with -Dlogaperture.followHandlers=false (see agent options); set logger then says why the handlers didn't follow.

logctl set logger io.undertow.request DEBUG for 5m --keep-handlers
io.undertow.request → DEBUG   (FOR, reverts 05:45:58 local — in 4m)
WARN: handler CONSOLE is at INFO and will drop DEBUG records from this logger.
      To see them: logctl set handler CONSOLE DEBUG

The same warning names any other handler that would drop the records, such as a file handler a vendor or the application set stricter. Lower it for a while, as the warning says:

logctl set handler CONSOLE DEBUG for 30m

or put it in AUTO for good, so it follows every change without being brought along:

logctl set handler CONSOLE AUTO sticky

logctl list handlers --show-all lists the handlers. ALL_HANDLERS means all of them at once, and DEFAULT_HANDLERS the ones that follow set logger.

Let logctl ask

On a terminal, leave out what you don't know. logctl set alone asks what to set, which logger (starting from part of its name, such as Worker), the level and the tier, then shows the full command before applying it, so you learn the one-line form for next time.

Put it back

A timed change reverts by itself. To undo it sooner, logctl reset logger io.undertow.request. See Undo changes.