Tiers and expiry¶
Every change logctl makes has a tier, which says how long it lasts. You give it at the end of
the command:
logctl set logger com.acme DEBUG for 30m
logctl set logger com.acme DEBUG session
logctl set logger com.acme DEBUG sticky
| Tier | Lasts until | Survives a restart |
|---|---|---|
for <duration> |
the time is up | yes, and keeps counting down |
session |
the JVM stops | no |
sticky |
you reset it |
yes |
A duration is a number and a unit: 30s, 30m, 4h, 2d.
The default is for 4h¶
set, add rule and apply recipe without a tier mean for 4h: a working session, gone by
morning. A change you forget about doesn't outlive the day you made it.
Two commands differ:
enable stormsanddisable stormswithout a tier last until the JVM stops (session): they switch a diagnostic on or off rather than change what is logged.alter rulewithout a tier keeps the rule's current lifetime.
How a timed change ends¶
LogAperture checks for changes that have run out every 30 seconds, so a for 5m change reverts
between 5 minutes and 5 minutes 30 seconds after you made it. The revert is written to the
audit log with source=expiry-sweep.
What survives a restart¶
sticky changes, and for changes that haven't run out, are saved in LogAperture's state
file and put back when the JVM starts again. A for change keeps counting from where it was: one
that ran out while the JVM was down is not put back, and its end is still audited. session
changes are never saved.
The state file is under ~/.logaperture/instances/ of the user running the JVM.
logctl env shows its exact path, and Agent options says how to
move it. It belongs to LogAperture: don't edit it.
When the application changes a level itself¶
Applications and servers change their own logging configuration too: a WildFly management command, a Logback configuration reload. When that happens to a logger or handler that has an override, LogAperture puts the override back:
- On WildFly, within about a second of a
/subsystem=loggingchange or a:reload, audited withsource=verification-sweep. - On Logback 1.3.14, 1.4.14 or 1.5.x, as soon as the reload finishes. This puts back the levels LogAperture already had in place, so it writes no audit line.
- Otherwise within the sweep interval, 30 seconds by default
(
logaperture.sweep.seconds), audited withsource=verification-sweep. That includes Logback 1.2.x, 1.3.0 and 1.4.0 when the file itself sets the logger's level, and a WildFly server started with-Djboss.server.persist.config=false.
The override wins until it ends. Then the logger goes back to the application's configuration as it is at that moment, including the change.
Seeing tiers¶
logctl status shows every active change with its tier and, for for, when it reverts:
LOGGER LEVEL TIER REVERTS REASON
io.undertow.request DEBUG FOR 05:01:22 (in 4m) โ
com.example.demo DEBUG SESSION until restart โ
com.example.other DEBUG STICKY until reset โ
reset skips sticky changes unless you add --include-sticky: you made them to last, so a bulk
reset doesn't remove them by accident. See Undo changes.