Logging

Configure the logging framework in BoxLang

This section configures the logging framework in BoxLang. Please note that BoxLang leverages RollingFileAppenders for most of its loggers. This provides consistency for the language and a consistent destination. You can customize it as you see fit, but this provides uniformity to the core and modules.

The loggingsection is divided into global log settings and a loggers section where you can configure named loggers in the runtime.

Please also note that in BoxLang, you can log data as text or as JSON.

boxlang.json

// Logging Settings for the runtime
"logging": {
	// The location of the log files the runtime will produce
	"logsDirectory": "${boxlang-home}/logs",
	// The number of days to keep rotated archive log files before they are deleted
	// Log files rotate when they reach maxFileSize, or when the day changes, whichever comes first
	// Default is 90 days or 3 months
	"maxLogDays": 90,
	// The maximum file size for a single log file before rotation
	// You can use the following suffixes: KB, MB, GB, or a bare number for bytes
	// Default is 100MB
	"maxFileSize": "100MB",
	// The total cap size of all log files combined before the oldest archives are deleted
	// You can use the following suffixes: KB, MB, GB, or a bare number for bytes
	// Default is 5GB
	"totalCapSize": "5GB",
	// The root logger level
	// Valid values are in order of severity: ERROR, WARN, INFO, DEBUG, TRACE, OFF
	// If the runtime is in Debug mode, this will be set to DEBUG
	"rootLevel": "WARN",
	// Default Encoder for file appenders.
	// The available options are "text" and "json"
	"defaultEncoder": "text",
	// Activate the status printer on load to print out the logging configuration
	// Turn on to debug LogBack and BoxLang logging configurations
	"statusPrinterOnLoad": false,
	// A collection of pre-defined loggers and their configurations
	"loggers": {
		// The runtime main and default log
		"runtime": {
			// Valid values are in order of severity: ERROR, WARN, INFO, DEBUG, TRACE, OFF
			// Leave out if it should inherit from the root logger
			//"level": "WARN",
			// Valid values are: "file", "console",
			// Coming soon: "smtp", "socket", "db", "syslog" or "java class name"
			// Please note that we only use Rolling File Appenders
			"appender": "file",
			// Use the defaults from the runtime
			"appenderArguments": {},
			// The available options are "text" and "json"
			"encoder": "text",
			// Additive logging: true means that this logger will inherit the appenders from the root logger
			// If false, it will only use the appenders defined in this logger
			"additive": true
		},
		// The modules log
		"modules": {
			// Valid values are in order of severity: ERROR, WARN, INFO, DEBUG, TRACE, OFF
			// Leave out if it should inherit from the root logger
			//"level": "WARN",
			// Valid values are: "file", "console",
			// Coming soon: "smtp", "socket", "db", "syslog" or "java class name"
			// Please note that we only use Rolling File Appenders
			"appender": "file",
			// Use the defaults from the runtime
			"appenderArguments": {},
			// The available options are "text" and "json"
			"encoder": "text",
			// Additive logging: true means that this logger will inherit the appenders from the root logger
			// If false, it will only use the appenders defined in this logger
			"additive": true
		},
		// All applications will use this logger
		"application": {
			// Valid values are in order of severity: ERROR, WARN, INFO, DEBUG, TRACE, OFF
			// Leave out if it should inherit from the root logger
			"level": "TRACE",
			// Valid values are: "file", "console",
			// Coming soon: "smtp", "socket", "db", "syslog" or "java class name"
			// Please note that we only use Rolling File Appenders
			"appender": "file",
			// Use the defaults from the runtime
			"appenderArguments": {},
			// The available options are "text" and "json"
			"encoder": "text",
			// Additive logging: true means that this logger will inherit the appenders from the root logger
			// If false, it will only use the appenders defined in this logger
			"additive": true
		},
		// All scheduled tasks logging
		"scheduler": {
			// Valid values are in order of severity: ERROR, WARN, INFO, DEBUG, TRACE, OFF
			// Leave out if it should inherit from the root logger
			"level": "INFO",
			// Valid values are: "file", "console",
			// Coming soon: "smtp", "socket", "db", "syslog" or "java class name"
			// Please note that we only use Rolling File Appenders
			"appender": "file",
			// Use the defaults from the runtime
			"appenderArguments": {},
			// The available options are "text" and "json"
			"encoder": "text",
			// Additive logging: true means that this logger will inherit the appenders from the root logger
			// If false, it will only use the appenders defined in this logger
			"additive": true
		},
		// All bx:http request lifecycle logging (start/completion, status code, elapsed time)
		"http": {
			// Valid values are in order of severity: ERROR, WARN, INFO, DEBUG, TRACE, OFF
			// Raise to DEBUG to log every request's start and completion
			"level": "INFO",
			// Valid values are: "file", "console",
			// Please note that we only use Rolling File Appenders
			"appender": "file",
			// Use the defaults from the runtime
			"appenderArguments": {},
			// The available options are "text" and "json"
			"encoder": "text",
			// Additive logging: true means that this logger will inherit the appenders from the root logger
			// If false, it will only use the appenders defined in this logger
			"additive": true
		}
	}
},

Global Properties

Logs Directory

This is the folder where BoxLang will store its log files. By default we use the following:

// The location of the log files the runtime will produce
"logsDirectory": "${boxlang-home}/logs",

Max Log Days

The number of days to keep rotated archive log files before they are deleted. The default is 90 days or 3 months.

Log files rotate when they reach maxFileSize, or when the day changes, whichever comes first. maxLogDays does not trigger rotation — it only controls how long already-rotated archives are retained.

"maxLogDays": 90,

Max File Size

The maximum filesize for a single log file before rotation occurs. The default is 100 Megabytes. You can use a number or the following suffixes: KB, MB, GB.

"maxFileSize": "100MB",

Total Cap Size

The total combined size cap of ALL archive log files. When the total size of the archives exceeds this value, the oldest archives are deleted to stay under the cap. The default is 5 Gigabytes. You can use a number or the following suffixes: KB, MB, GB.

"totalCapSize": "5GB",

Root Level

This is the level at which the root logger will be allowed to be logged. By default, it is WARN, However, if it detects you are in debug mode, it will bump it to DEBUG.

"rootLevel": "WARN",

Default Encoder

By default, BoxLang is configured to log using a pattern textual encoder. However, if you want to leverage the new JSON Lines format, you can switch the encoder for ALL loggers to be JSON. Valid values are text or json

"defaultEncoder" : "text"

Status Printer On Load

Activate the status printer on load to print out the logging configuration. This is useful for debugging LogBack and BoxLang logging configurations. The default is false.

// Activate the status printer on load to print out the logging configuration
// Turn on to debug LogBack and BoxLang logging configurations
"statusPrinterOnLoad": false

Loggers

BoxLang allows you to pre-define named loggers that will be configured when used via BoxLang calls to:

• writeLog() BIF
• log component

However, you can also retrieve named loggers via the LoggingService. By default, we will register the following named loggers:

• runtime - The default log file for all runtime-related logging
• async - All async operations and facilities will log here
• cache - All cache operations and facilities will log here
• datasource - Used by the creation, debugging, and management of datasources
• modules - For all modular information, activation, etc
• application - Application-specific logs
• scheduler - All tasks and schedulers can log here
• http - bx:http request lifecycle; raise to DEBUG to log every request's start/completion, status code, and elapsed time

Logger Properties

Every logger has the following configuration properties:

"runtime": {
    // Valid values are in order of severity: ERROR, WARN, INFO, DEBUG, TRACE, OFF
    // Leave out if it should inherit from the root logger
    //"level": "WARN",
    // Valid values are: "file", "console",
    // Coming soon: "smtp", "socket", "db", "syslog" or "java class name"
    // Please note that we only use Rolling File Appenders
    "appender": "file",
    // Use the defaults from the runtime
    "appenderArguments": {},
    // The available options are "text" and "json"
    "encoder": "text",
    // Additive logging: true means that this logger will inherit the appenders from the root logger
    // If false, it will only use the appenders defined in this logger
    "additive": true
},

Each logger will have the following configuration items:

Property	Default	Type	Description
additive	true	boolean	true means that this logger will inherit the appenders from the root logger and log through all of them. false means it doesn't bubble up log messages.
appender	file	string	The type of appender to use for this logger. By default we use the rolling file appender. Valid values are: - file - console Coming soon values: - smtp - socket - db - syslog - class name
appenderArguments	---	object	Name-value pairs that configure the appender. Each appender can have different arguments.
categories	[]	array	A list of Java package or class names whose log output will be routed to this logger. Whitespace is trimmed from each entry. Loggers with level: OFF skip appender creation entirely.
encoder	logging > defaultEncoder	text or json	The encoder to use for logging. By default it leverages what was defined in the logging.defaultEncoder configuration.
level	Inherits from logging > rootLevel	logLevel	The log level assigned to the logger. If omitted, the logger inherits the level from logging > rootLevel (e.g. WARN).

Logger Categories

The categories property lets you redirect third-party Java library log output to a specific BoxLang logger. Any Java package or class name listed in categories will have its events captured by that logger at the configured level, with no propagation to parent loggers (non-additive routing).

BoxLang ships with a built-in blackhole logger configured at level: OFF. Add any noisy library package to its categories to silence it completely with zero I/O overhead:

"blackhole": {
    "level": "OFF",
    "appender": "file",
    "appenderArguments": {},
    "encoder": "text",
    "additive": false,
    "categories": [
        "com.zaxxer.hikari",
        "org.springframework"
    ]
}

To route library output to a dedicated file instead of suppressing it:

"thirdparty-db": {
    "level": "WARN",
    "appender": "file",
    "encoder": "text",
    "additive": false,
    "categories": [
        "com.zaxxer.hikari",
        "org.apache.commons.dbcp2"
    ]
}

Always set "additive": false on loggers used for category routing. Otherwise matched events will also propagate up to the root logger.