JSON output¶
Every logctl command except export vendor-defaults takes --json, and then prints one line of
JSON on standard output instead of text. With --json, logctl never asks a question: a command
that would need an answer fails instead, as it does off a terminal.
The examples below are formatted for reading. They were captured from WildFly 26.1.3.
What stays the same¶
From 1.0.0, within a major version:
- A field is never removed or renamed, and never changes its type or meaning.
- New fields can appear in any release. Ignore fields you don't know.
- New values can appear in fields that hold a name from a fixed set, such as a severity or a tier.
The same promise covers the agent's management interface; see the versioning rules.
Conventions¶
- Times are UTC, in ISO-8601:
2026-10-09T05:42:12.441226621Z. - Levels are names:
TRACE,DEBUG,INFO,WARN,ERROR,OFF,ALL. - Tiers are
SESSION,FORorSTICKY.expiresAtis set forFORandnullotherwise. - A field that doesn't apply is
null, not left out. sourcenames where a change came from:jmxfor a change made withlogctl,resumefor astickychange restored at startup,expiry-sweepandverification-sweepfor LogAperture's own periodic work,vendor-defaultsandrecipefor changes from those.contextnames the logging context a row belongs to; on WildFly the server's own issystem.- On a failure, the exit code says what went wrong (below) and the message goes to standard error, as text.
Exit codes¶
| Code | Means |
|---|---|
0 |
Done. |
1 |
Unexpected error. |
2 |
The command line is wrong. |
3 |
No JVM with the agent was found. |
4 |
Several JVMs with the agent were found, and logctl couldn't ask which: 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. |
Loggers¶
list loggers¶
The loggers shown, one object per logger, under loggers.
logctl list loggers io.undertow --json
{
"loggers": [
{
"name": "io.undertow.request",
"configuredLevel": null,
"effectiveLevel": "DEBUG",
"overrideActive": true,
"overrideSource": "jmx",
"overrideReason": "demo",
"tier": "FOR",
"expiresAt": "2026-10-10T04:32:09.361891539Z",
"vendorDefaultLevel": null,
"resetToNative": false,
"recipe": null,
"forcedBy": null
}
]
}
status¶
The loggers with an override (same fields as list loggers), the handlers with one, the rules
(same object per rule as add rule, leaving out vendor rules nobody has changed), the
vendor defaults file if any, and storm detection's state.
logctl status --json
{
"loggers": [
{
"name": "com.example.kept",
"configuredLevel": null,
"effectiveLevel": "DEBUG",
"overrideActive": true,
"overrideSource": "jmx",
"overrideReason": null,
"tier": "STICKY",
"expiresAt": null,
"vendorDefaultLevel": null,
"resetToNative": false,
"recipe": null,
"forcedBy": null
}
],
"handlerOverrides": [],
"rules": [
{
"id": "r1",
"loggerName": "io.undertow.request",
"action": "drop",
"levelAtMost": "INFO",
"messageContains": "Matched default",
"messageIgnoreCase": false,
"throwableType": null,
"throwableMessageContains": null,
"anyCause": false,
"reason": "health checks",
"tier": "FOR",
"expiresAt": "2026-10-10T07:33:38.543016798Z",
"createdAt": "2026-10-10T03:33:38.543016798Z",
"context": "system",
"hitCount": 0,
"frames": null,
"collapseCauses": null,
"origin": null,
"toNative": false,
"altered": false,
"recipe": null,
"sampleFullEnabled": true,
"sampleFullEveryMillis": 300000,
"expression": "--message-contains \"Matched default\" --below WARN --sample-full 5m"
}
],
"vendorDefaults": null,
"stormDetection": {
"enabled": false,
"changedAt": null,
"tier": "SESSION",
"expiresAt": null
}
}
set logger¶
The overrides made (several for a pattern target or --force), the handlers whose level would
hide the new output (warnings), the descendants --force reached, and the default handlers that
now follow the change (following; see Raise a log level).
A handler in following has carriesOn: true when your own setting on it still applies, with that
setting's tier and deadline in ownTier and ownExpiresAt; it follows the change once that ends.
followDenied names the capability that kept the default handlers from following, if one did.
logctl set logger io.undertow.request DEBUG for 30m --reason demo --json
{
"overrides": [
{
"loggerName": "io.undertow.request",
"level": "DEBUG",
"reason": "demo",
"appliedAt": "2026-10-17T05:41:00.098475751Z",
"source": "jmx",
"tier": "FOR",
"expiresAt": "2026-10-17T06:11:00.098475751Z",
"forcedBy": null
}
],
"warnings": [],
"descendants": [],
"following": [
{
"handlerRef": "CONSOLE",
"previousLevel": "INFO",
"level": "DEBUG",
"follows": [
"io.undertow.request"
],
"carriesOn": false,
"ownTier": null,
"ownExpiresAt": null
}
],
"followDenied": null
}
reset¶
reset logger prints the logger after the reset, plus what it did to rules and forced
descendants under it. reset loggers and reset handlers print what was reverted and which
sticky overrides were skipped. reset rule prints the rule's fate.
logctl reset logger io.undertow.request --json
{
"name": "io.undertow.request",
"configuredLevel": null,
"effectiveLevel": "INFO",
"overrideActive": false,
"overrideSource": null,
"overrideReason": null,
"tier": null,
"expiresAt": null,
"vendorDefaultLevel": null,
"resetToNative": false,
"recipe": null,
"forcedBy": null,
"removedRuleIds": [],
"skippedStickyRuleIds": [],
"vendorResetRuleIds": [],
"forcedRevertedLoggerNames": [],
"forcedSkippedStickyLoggerNames": []
}
logctl reset handlers --json
{
"revertedHandlerRefs": [
"CONSOLE"
],
"skippedStickyHandlerRefs": []
}
logctl reset rule r1 --json
{
"id": "r1",
"removed": true,
"vendorReset": false,
"toNative": false
}
Handlers¶
list handlers¶
logctl list handlers --json
{
"handlers": [
{
"ref": "CONSOLE",
"level": "DEBUG",
"persistent": false,
"targetPath": null,
"autoFlush": true,
"overrideActive": true,
"overrideLevel": "DEBUG",
"overrideMode": "AUTO",
"overrideTier": "FOR",
"overrideExpiresAt": "2026-10-17T06:11:00.098475751Z",
"membersSummary": null,
"context": "system",
"vendorDefault": null,
"resetToNative": false,
"recipe": null,
"follows": [
"io.undertow.request"
],
"thenFollows": []
}
]
}
set handler¶
logctl set handler CONSOLE DEBUG for 10m --json
{
"handlerRef": "CONSOLE",
"level": "DEBUG",
"mode": "FIXED",
"reason": null,
"appliedAt": "2026-10-09T05:12:26.576398427Z",
"source": "jmx",
"tier": "FOR",
"expiresAt": "2026-10-09T05:22:26.576398427Z",
"warnings": [],
"follows": [],
"thenFollows": []
}
Rules¶
add rule¶
The rule as created. levelAtMost is the most severe level it acts on: --below ERROR makes it
WARN. expression is the rule's options in the form alter rule takes. list rules prints
{"rules": [...]} with the same object per rule.
logctl add rule drop io.undertow.request --message-contains "Matched default" --json
{
"id": "r1",
"loggerName": "io.undertow.request",
"action": "drop",
"levelAtMost": "WARN",
"messageContains": "Matched default",
"messageIgnoreCase": false,
"throwableType": null,
"throwableMessageContains": null,
"anyCause": false,
"reason": null,
"tier": "FOR",
"expiresAt": "2026-10-09T09:12:24.572167230Z",
"createdAt": "2026-10-09T05:12:24.572167230Z",
"context": "system",
"hitCount": 0,
"frames": null,
"collapseCauses": null,
"origin": null,
"toNative": false,
"altered": false,
"recipe": null,
"sampleFullEnabled": true,
"sampleFullEveryMillis": 300000,
"expression": "--message-contains \"Matched default\" --below ERROR --sample-full 5m"
}
alter rule¶
The rule after the change, with every field add rule prints (shortened here), plus what it was
before and whether anything changed.
logctl alter rule r1 --below WARN --json
{
"id": "r1",
"levelAtMost": "INFO",
"expression": "--message-contains \"Matched default\" --below WARN --sample-full 5m",
"previousExpression": "--message-contains \"Matched default\" --below ERROR --sample-full 5m",
"previousTier": "FOR",
"previousExpiresAt": "2026-10-09T09:12:24.572167230Z",
"changed": true
}
Diagnostics¶
doctor¶
check is one of the check ids. checksRun counts the checks that ran. Two
of the findings are shown here.
logctl doctor --json
{
"findings": [
{
"check": "handler.unbounded-growth",
"severity": "WARNING",
"subject": "FILE",
"summary": "FILE has no size cap — writes are unbounded.",
"detail": "no size-based rotation is configured",
"suggestedFix": "configure a size-based rotation policy on FILE.",
"context": "system"
},
{
"check": "disk.headroom",
"severity": "OK",
"subject": "overlay:overlay",
"summary": "/opt/jboss/wildfly/standalone/log/server.log is stable — no writes observed during the sample window.",
"detail": null,
"suggestedFix": null,
"context": "system"
}
],
"checksRun": 5
}
top¶
Byte counts since measurementStartedAt, worst first. The text output's rates and daily
projections are worked out from these.
logctl top --limit 2 --json
{
"loggers": [
{
"loggerName": "org.logaperture.sample.work.Worker",
"totalBytes": 1170,
"stackTraceBytes": 0,
"context": "system"
},
{
"loggerName": "org.wildfly.extension.undertow",
"totalBytes": 864,
"stackTraceBytes": 0,
"context": "system"
}
],
"measurementStartedAt": "2026-10-09T04:56:07.092712548Z",
"trackedCount": 14
}
storms¶
logctl storms --json
{
"storms": [
{
"loggerName": "io.undertow.request",
"level": "DEBUG",
"throwableClass": null,
"normalizedMessage": "Matched default handler path %s",
"topFrames": null,
"status": "ONGOING",
"firstEventAt": "2026-10-10T02:41:22.667701316Z",
"lastEventAt": "2026-10-10T02:41:26.038228375Z",
"endedAt": null,
"eventCount": 1500,
"firstOccurrence": "2026-10-10T02:41:24.990134470Z DEBUG [io.undertow.request] Matched default handler path /x997",
"sampleEventNumber": 1000,
"context": "system"
}
],
"trackedCount": 1,
"ongoingCount": 1,
"measurementStartedAt": "2026-10-10T02:41:21.497247862Z",
"notRetainedCount": 0,
"detectionEnabled": true,
"detectionChangedAt": "2026-10-10T02:41:21.486477057Z"
}
firstOccurrence is the storm's sample: the event that took it over the threshold, with its
message as logged and its stack trace, if any. sampleEventNumber says which event of the storm
that was, counted from firstEventAt; it is 0 from an older agent that doesn't report it.
enable storms, disable storms¶
logctl enable storms --json
{
"enabled": true,
"previous": false,
"changedAt": "2026-10-09T05:12:31.219692216Z",
"tier": "SESSION",
"expiresAt": null
}
env¶
logctl env --json
{
"agentVersion": "1.0.0",
"cliVersion": "1.0.0",
"javaVersion": "17.0.5",
"javaVendor": "Eclipse Adoptium",
"osName": "Linux",
"osVersion": "7.2.10-200.fc44.x86_64",
"osArch": "amd64",
"backendName": "JBoss LogManager",
"backendVersion": "2.1.18.Final",
"containerName": "WildFly",
"containerVersion": "26.1.3.Final",
"diagnosticsLevel": null,
"stateFilePath": "/opt/jboss/wildfly/standalone/tmp/logaperture/instances/af001a751ad6462d-jboss.state.yaml",
"vendorDefaultsPath": null,
"vendorDefaultsStatus": "not configured"
}