Vendor defaults¶
If you ship a product that runs on a JVM, its customers inherit its logging. A vendor defaults
file lets you ship sensible logging settings with the product, so customers don't start with
noisy logs or have to run logctl commands after every install.
The file is given to the agent at startup:
-javaagent:/opt/logaperture/lib/logaperture-agent.jar=--vendor-defaults=/opt/myproduct/logging.yaml
It can set logger levels, handler levels, DEFAULT_HANDLERS, and drop and trim rules. It can
also offer recipes for customers to switch on when they need them.
What the file does¶
For every setting it names, the file replaces the application's own logging configuration. Your customers' operators then work on top of it:
logctl list loggersshows the file's level in aVENDORcolumn.resetgoes back to the file's settings, not to the application's configuration. That's what makes the file a baseline; see Configuration layers.reset … --to-nativegoes back to the application's own configuration until restart, for a customer who needs to see what the product would log without your settings.- The file's rules have
vendor:ids. A customer can change one withalter rule, andreset ruleputs yours back.
The file is never written by LogAperture. If it has an error, none of it applies, the agent
starts anyway, and logctl doctor lists every error with its line number. Check a new file
before you ship it.
Making the file: tune, then export¶
You don't need to write the file by hand. Run the product in a test environment, tune its logging
live with sticky changes until it is right, then export. The film shows a logger and a rule
exported.
In text, from an earlier run that also sets a handler:
logctl set logger org.jboss.as.server.deployment WARN sticky
logctl set handler CONSOLE INFO sticky
logctl add rule drop io.undertow.request --message-contains "Matched default" --below WARN sticky
logctl export vendor-defaults --out logging.yaml
# Exported by logctl export vendor-defaults, 2026-10-16T01:45:07Z, agent 1.0.0
# Started from: no vendor defaults file
schemaVersion: 1
loggers:
- name: org.jboss.as.server.deployment
level: WARN
stateId: 937f83b2-c403-4735-8999-47cc17dd5c3e
handlers:
- name: CONSOLE
level: INFO
stateId: 51eca665-4862-47c7-a4ba-41b0c8187919
rules:
# was r1
- id: drop-request
action: drop
logger: io.undertow.request
messageContains: "Matched default"
below: WARN
sampleFull: 5m
stateId: 0d5498e8-4026-4da9-ab36-c3b104e7dfb0
The export is the file the JVM started with, plus every sticky change on top of it. session and
for changes are left out: only what you meant to keep is exported. So is a handler that is only
following a sticky logger change: it went to AUTO for that change, not as a setting of its own.
To ship a handler in AUTO, set it yourself (logctl set handler CONSOLE AUTO sticky).
The stateId lines connect each entry to the sticky change it came from. When you restart with
the new file, the file takes those changes over, so each setting is active once, from the file.
Later edits to the file then take effect on the next restart.
Taking an entry out¶
To remove a setting from the next version of the file, return it to the application's own
configuration before exporting. For a logger the current file sets to DEBUG, whose native
configuration says INFO:
| Before exporting, you run | The next file says |
|---|---|
| nothing | DEBUG, unchanged |
set logger org.perfmon4j WARN sticky |
WARN |
set logger org.perfmon4j INFO sticky |
INFO, fixed even if the native configuration changes later |
reset logger org.perfmon4j --to-native |
nothing: the native configuration decides from now on |
Shipping it¶
- Put the file where the JVM's account can't write it. Otherwise anyone who can run code as
that account can change your baseline.
doctorwarns when it can (vendor-defaults.writable). - Use exact logger names. The file doesn't accept
*patterns. - Handlers may not exist yet at startup. A handler the file names is applied as soon as it
appears. On WildFly some appear after startup;
doctorreports one that never does. - Storm detection isn't set in the file. Use the
--storm-detection=onagent argument.
The full format is in File formats.