Skip to content

File formats

LogAperture reads two kinds of file you write: the vendor defaults file and recipe files. Both are YAML, in a deliberately small subset.

The YAML subset

Supported: maps, lists of maps, one-line lists ([CONSOLE, FILE]), plain and double-quoted values, # comments, and multi-line text written as key: | followed by indented lines.

Not supported: tabs for indentation, anchors and aliases (&, *), several documents in one file, and the other multi-line forms (>, |-, |+). A file that uses them is rejected.

A file is checked as a whole before any of it is used, and every error is reported with its line number, not just the first. Unknown keys are errors, so a typo like levle: is caught.

Vendor defaults file

Given to the agent with --vendor-defaults=<file>. Every setting it names replaces the application's own; see Vendor defaults. If the file has any error, none of it applies: logctl doctor lists the errors.

schemaVersion: 1

loggers:
  - name: org.hibernate.SQL
    level: WARN
  - name: com.acme.support
    level: DEBUG
    reason: "support asked for this by default"

handlers:
  - name: FILE
    level: INFO
  - name: CONSOLE
    level: AUTO

defaultHandlers: [CONSOLE]

rules:
  - id: healthcheck-noise
    action: drop
    logger: com.acme.health
    messageContains: "ping ok"
    below: WARN
    reason: "load balancer health probes"
  - id: autoupdate-trace
    action: trim
    logger: com.acme.AutoUpdateHelper
    throwable: java.net.ConnectException
    frames: 0
Key Required Contains
schemaVersion yes 1
loggers no name (an exact logger name, no *), level, reason
handlers no name (as logctl list handlers shows it), level (a level or AUTO), reason
defaultHandlers no the handlers DEFAULT_HANDLERS means
rules no drop and trim rules, below
namespace with recipes the namespace of the file's recipe ids
recipes no recipes the file offers, as in a recipe file; loading the file doesn't apply them

A handler named in the file that doesn't exist yet is not an error: it is applied when the handler appears, and doctor reports it until then.

Rules

Each rule's fields are named after the logctl add rule options. Fields left out take the add rule defaults. Vendor rules have no tier: they last as long as the file is in use.

Field For logctl add rule option
id (required) both none. Lowercase letters, digits and -, up to 40. The rule's id becomes vendor:<id>.
action (required) both drop or trim
logger (required) both the target; an exact logger name
below both --below; a level, or FATAL for every level
messageContains, messageContainsIgnoreCase both --message-contains, --message-contains-ignore-case
throwable both --throwable
throwableMessageContains both --throwable-message-contains
anyCause both --any-cause (true or false)
sampleFull drop --sample-full, a duration; or false for --no-sample-full
frames trim --frames
collapseCauses trim --collapse-causes (true or false)
reason both --reason

Files written by export vendor-defaults

logctl export vendor-defaults writes this format. Entries that came from a sticky change carry an extra stateId field (and the file may have handlerGroupStateIds and defaultHandlersStateId). They let a restart with the new file take over those changes instead of applying them twice. A file you write by hand never needs them.

Recipe files

A recipe is a named set of settings for watching one thing. Recipe files come from three places:

Source Where May contain
A library META-INF/logaperture/recipes.yaml on its class path logger levels that raise verbosity
The vendor defaults file its recipes: key logger levels, handler levels, rules
The recipes folder any *.yaml in ~/.logaperture/recipes, or the folder named by -Dlogaperture.recipes logger levels, handler levels, rules
schemaVersion: 1
namespace: io.undertow
recipes:
  - name: sessions
    summary: Watch HTTP session creation, expiry and invalidation
    description: |
      Logs each session create/expire/invalidate with its id. Moderate volume
      under load. Session ids are sensitive; don't leave this on.
    loggers:
      - name: io.undertow.server.session
        level: DEBUG
        reason: session lifecycle events
      - name: io.undertow.request
        level: DEBUG
Key Required Contains
schemaVersion yes 1
namespace yes lowercase letters, digits, . and -, up to 64. A reverse domain you control, such as a library's Maven group id. vendor, logaperture and org.logaperture are reserved.
recipes yes the recipes
recipes[].name yes lowercase letters, digits and -, up to 40. The recipe's id is <namespace>:<name>.
recipes[].summary yes one line, shown by list recipes
recipes[].description no longer text, shown by show recipe
recipes[].loggers name, level, reason, as in the vendor defaults file
recipes[].handlers as in the vendor defaults file; not in a library's file
recipes[].rules as in the vendor defaults file, with id optional; not in a library's file

A recipe must change at least one thing. A file with an error offers none of its recipes; logctl list recipes --verbose and doctor report it. A library's recipe that would lower a level is skipped, since a library can only offer more visibility, never less.

Where a library's file goes in a war or an ear is covered in Recipes for library authors.