Script logctl¶
logctl works the same in a script, a cron job or a monitoring check as on a terminal, with two
differences: it never asks a question, and you can ask it for JSON.
It never asks off a terminal¶
On a terminal, logctl asks for anything a command leaves out and lists matches to pick from. Off a
terminal it can't, so an incomplete command fails with exit code 2 and says what's missing:
'set' needs 'logger <target> <level>', 'handler <name> <level>', or 'default-handler <name> ...'.
Run this in a terminal to be prompted for the missing parts.
Give the whole command. Where a command would ask for confirmation, add --yes:
- a pattern target (
set logger '*.Worker' DEBUG --yes,add rule … '*.Worker' … --yes) takes every match; apply recipe … --yesapplies without showing the changes first.
--json never asks either.
Pick the JVM explicitly¶
With several JVMs running the agent, logctl can't ask which one, and exits with code 4. In a
script, always pass --pid. See Work with several JVMs.
JSON¶
Add --json to any command except export vendor-defaults for one line of JSON on standard output:
logctl status --json | jq '.loggers[] | select(.tier == "STICKY") | .name'
The fields of each command are in JSON output. From 1.0.0, fields are only ever added within a major version, so ignore fields you don't know.
Exit codes¶
| Code | Means |
|---|---|
0 |
Done. |
1 |
Unexpected error. |
2 |
The command line is wrong, or incomplete off a terminal. |
3 |
No JVM with the agent was found. |
4 |
Several JVMs with the agent were found: pass --pid. |
5 |
logctl couldn't attach to the JVM: run it as the user running the JVM. |
6 |
The agent's policy doesn't allow this operation. |
doctor exits 0 whatever it finds; read its findings from --json to act on them.
Examples¶
Raise a level for the length of a support call, with the ticket number in the audit trail:
logctl --pid "$PID" set logger com.acme.billing DEBUG for 45m --reason "$TICKET"
Fail a health check when doctor finds anything critical:
logctl --pid "$PID" doctor --json \
| jq -e '[.findings[] | select(.severity == "CRITICAL")] | length == 0' > /dev/null
Undo everything a script set, keeping sticky changes made by people:
logctl --pid "$PID" reset loggers
logctl --pid "$PID" reset rules