Logbox

LogBox Skill

When to Use This Skill

Load this skill when:

• Installing or configuring LogBox (standalone or in ColdBox)
• Choosing and configuring appenders (console, file, rolling, DB, scope, socket, email)
• Setting up categories, the root logger, or category-level inheritance
• Injecting loggers into services, handlers, or interceptors via WireBox
• Using structured extraInfo logging or implementing $toString()
• Writing performant logging using canDebug() / closure messages
• Building custom appenders or layouts
• Configuring different log levels per environment

Language Mode Reference

Examples default to BoxLang (.bx) syntax. Adapt as needed:

CFML Compat: BoxLang + CFML Compat module lets .bx and .cfc files coexist. Use class {} for BoxLang-native, component {} for CFML-compat.

Architecture Overview

LogBox has five components that work together:

1. LogBox — central library storing loggers, appenders, categories, and configuration
2. Logger — sends messages to appropriate destinations according to its category
3. Categories — each logger has a unique category, typically a dot-notation class path
4. Appenders — components that receive log events and write them to a destination
5. Layouts — control the message format sent by an appender

Log Levels

Levels run from most severe (0) to most verbose (5):

levelMin / levelMax define the window of levels an appender or category accepts. Use numeric integers or string names interchangeably.

Installation

ColdBox Applications

LogBox is bundled with ColdBox. Configure it in config/LogBox.cfc (by convention) or inline in config/ColdBox.cfc.

Standalone

# Install via CommandBox
box install logbox

Add the mapping in Application.cfc:

this.mappings[ "/logbox" ] = expandPath( "/path/to/logbox" );

Standalone namespace: logbox.system.logging ColdBox namespace: coldbox.system.logging

Verify standalone installation:

logbox = new logbox.system.logging.LogBox();

LogBox Configuration DSL

The same DSL works in all three contexts:

• config/LogBox.cfc — standalone CFC with configure() method
• config/ColdBox.cfc logbox variable — inline ColdBox config
• Struct literal passed to the LogBox constructor (standalone)

Full DSL Reference

logBox = {
    appenders  : {},   // Required: one or more appender definitions
    root       : {},   // Required: root logger settings
    categories : {},   // Optional: named category overrides (granular)
    fatal      : [],   // Optional: array of category names → FATAL only
    error      : [],   // Optional: array of category names → ERROR only
    warn       : [],   // Optional: array of category names → WARN only
    info       : [],   // Optional: array of category names → INFO only
    debug      : [],   // Optional: array of category names → DEBUG only
    off        : []    // Optional: array of category names → logging off
}

Appender Keys

Root Logger Keys

Category Keys

Same as root logger, plus name. When no config is found for a requested category, LogBox walks up the dot-notation hierarchy to the first ancestor that is configured, then falls back to root.

Configuration Examples

Standalone config/LogBox.cfc

// BoxLang
class extends="logbox.system.logging.config.LogBoxConfig" {

    function configure() {

        appenders = {
            console : {
                class    : "logbox.system.logging.appenders.ConsoleAppender",
                levelMin : "DEBUG",
                levelMax : "FATAL"
            },
            fileApp : {
                class      : "logbox.system.logging.appenders.FileAppender",
                levelMin   : "INFO",
                levelMax   : "FATAL",
                properties : {
                    filePath   : "/app/logs",
                    fileName   : "application",
                    autoExpand : false
                }
            },
            rollingApp : {
                class      : "logbox.system.logging.appenders.RollingFileAppender",
                levelMin   : "WARN",
                levelMax   : "FATAL",
                properties : {
                    filePath        : "/app/logs",
                    fileName        : "app",
                    autoExpand      : false,
                    fileMaxSize     : 5000,
                    fileMaxArchives : 5
                }
            }
        }

        root = {
            levelMin  : "WARN",
            levelMax  : "FATAL",
            appenders : "rollingApp"
        }

        categories = {
            "models"           : { levelMin : "DEBUG", levelMax : "INFO",  appenders : "console,fileApp" },
            "models.UserService" : { levelMin : "DEBUG", levelMax : "DEBUG", appenders : "console" }
        }

        // Shorthand: put these categories at DEBUG level using root appenders
        debug = [ "coldbox.system.interceptors" ]

        // Silence noisy third-party packages
        off = [ "coldbox.system.plugins.BeanFactory" ]
    }
}

// CFML equivalent
component extends="coldbox.system.logging.config.LogBoxConfig" {

    function configure() {

        appenders = {
            console : {
                class    : "coldbox.system.logging.appenders.ConsoleAppender",
                levelMin : "DEBUG",
                levelMax : "FATAL"
            },
            rollingApp : {
                class      : "coldbox.system.logging.appenders.RollingFileAppender",
                levelMin   : "WARN",
                levelMax   : "FATAL",
                properties : {
                    filePath        : "/app/logs",
                    fileName        : "app",
                    autoExpand      : false,
                    fileMaxSize     : 5000,
                    fileMaxArchives : 5
                }
            }
        }

        root = { levelMin : "WARN", levelMax : "FATAL", appenders : "rollingApp" }

        categories = {
            "models" : { levelMin : "DEBUG", levelMax : "INFO", appenders : "console" }
        }
    }
}

ColdBox Inline Config (config/ColdBox.cfc)

// Inside configure() — shared across all environments
logbox = {
    appenders : {
        console : {
            class    : "coldbox.system.logging.appenders.ConsoleAppender",
            levelMin : "DEBUG",
            levelMax : "FATAL"
        },
        rolling : {
            class      : "coldbox.system.logging.appenders.RollingFileAppender",
            levelMin   : "WARN",
            levelMax   : "FATAL",
            properties : {
                filePath        : "#getDirectoryFromPath( getBaseTemplatePath() )#logs",
                fileName        : "app",
                fileMaxSize     : 5000,
                fileMaxArchives : 3
            }
        }
    },
    root       : { levelMin : "WARN", levelMax : "FATAL", appenders : "rolling" },
    categories : {}
}

// Development override — verbose, no file I/O
function development() {
    logbox.root = { levelMin : "DEBUG", levelMax : "FATAL", appenders : "console" }
}

// Production override — only warnings and above to rolling file
function production() {
    logbox.root = { levelMin : "WARN", levelMax : "FATAL", appenders : "rolling" }
}

ColdBox Config File Pointer

// In config/ColdBox.cfc — point to an external file
logbox = { configFile : "config/LogBox" }
// or with a package path
logbox = { configFile : "myapp.config.LogBox" }

Standalone Instantiation

// Direct struct config (no CFC needed)
var logbox = new logbox.system.logging.LogBox( {
    appenders : {
        console : { class : "logbox.system.logging.appenders.ConsoleAppender" }
    },
    root : { levelMax : "DEBUG", appenders : "*" }
} )

var log = logbox.getLogger( "myapp.services.UserService" )
log.info( "LogBox running standalone" )

Built-In Appenders

Use the short class name (relative to coldbox.system.logging.appenders. or logbox.system.logging.appenders.) or the full path.

ConsoleAppender

Writes to the system console/stdout. Ideal for development and Docker containers.

console : {
    class : "coldbox.system.logging.appenders.ConsoleAppender"
    // No required properties
}

FileAppender

Writes to a single log file (appends forever — no rotation).

fileApp : {
    class      : "coldbox.system.logging.appenders.FileAppender",
    properties : {
        filePath     : "/app/logs",      // Required — directory path
        fileName     : "application",    // Optional — defaults to appender name
        fileEncoding : "UTF-8",          // Optional — default UTF-8
        autoExpand   : false             // Set false for absolute paths
    }
}

Always set autoExpand : false when using absolute file paths.

RollingFileAppender

Writes to a file and automatically rotates when the file exceeds a size limit.

rollingApp : {
    class      : "coldbox.system.logging.appenders.RollingFileAppender",
    properties : {
        filePath        : "/app/logs",   // Required
        fileName        : "app",         // Optional
        fileEncoding    : "UTF-8",       // Optional
        autoExpand      : false,         // Set false for absolute paths
        fileMaxSize     : 2000,          // KB — default 2000 (2 MB)
        fileMaxArchives : 2              // Number of archived files to keep — default 2
    }
}

DBAppender

Writes log entries to a database table.

dbLog : {
    class      : "coldbox.system.logging.appenders.DBAppender",
    levelMin   : "ERROR",
    levelMax   : "FATAL",
    properties : {
        dsn          : "myDSN",        // Required
        table        : "app_logs",     // Required
        autocreate   : true,           // Create table if not exists — default false
        rotate       : true,           // Delete old records — default true
        rotationDays : 30              // Days to keep records — default 30
    }
}

Table columns (when autocreate : true): id (UUID), severity, category, logdate, appendername, message, extrainfo.

Use columnMap to alias your own column names:

properties : {
    dsn       : "myDSN",
    table     : "logs",
    columnMap : {
        severity   : "log_level",
        category   : "log_category",
        message    : "log_message",
        extrainfo  : "log_extra"
    }
}

ScopeAppender

Stores log entries in a CF/BoxLang scope (useful for debugging in-request).

scopeLog : {
    class      : "coldbox.system.logging.appenders.ScopeAppender",
    properties : {
        scope : "request",          // Any valid scope — default "request"
        key   : "logs",             // Key within the scope — default appender name
        limit : 50                  // Max entries to keep (0 = unlimited, default)
    }
}

SocketAppender

Transmits log events over a TCP socket.

socketApp : {
    class      : "coldbox.system.logging.appenders.SocketAppender",
    properties : {
        host              : "logserver.example.com",
        port              : 5000,
        timeout           : 3,
        persistConnection : false
    }
}

EmailAppender

Sends log events via email (use sparingly — FATAL/ERROR only).

emailAlert : {
    class      : "coldbox.system.logging.appenders.EmailAppender",
    levelMin   : "FATAL",
    levelMax   : "ERROR",
    properties : {
        from    : "errors@example.com",
        to      : "ops@example.com",
        subject : "[PROD] Application Error"
    }
}

Async Logging

Any appender can log asynchronously. Add async : true to its config:

fileApp : {
    class      : "coldbox.system.logging.appenders.FileAppender",
    async      : true,
    properties : { filePath : "/app/logs" }
}

WireBox Injection DSL

The logbox: DSL prefix is available in any WireBox-managed component.

// BoxLang
class UserService {

    // Best practice: category auto-matches class path
    @inject( "logbox:logger:{this}" )
    property name="log";

    // Access the LogBox instance itself
    @inject( "logbox" )
    property name="logBox";
}

// CFML
component {
    property name="log"    inject="logbox:logger:{this}";
    property name="logBox" inject="logbox";
}

Logger API

Logging Methods

message can be a string or a closure (see performance section). extraInfo can be any value: string, struct, query, array, object.

Utility Methods

LogBox Methods

Logger Usage Patterns

Basic Usage in a Service

class OrderService {

    @inject( "logbox:logger:{this}" )
    property name="log";

    function processOrder( required order ) {
        log.info( "Processing order ##order.getId()" )

        try {
            var result = paymentGateway.charge( order )
            log.info( "Payment successful", { transactionId : result.id, amount : result.amount } )
            return result
        } catch( PaymentException e ) {
            log.error( "Payment failed for order ##order.getId()", e )
            rethrow
        }
    }
}

component {

    property name="log" inject="logbox:logger:{this}";

    function processOrder( required order ) {
        log.info( "Processing order ##order.getId()" )

        try {
            var result = paymentGateway.charge( order )
            log.info( "Payment successful", { transactionId : result.id, amount : result.amount } )
            return result
        } catch( PaymentException e ) {
            log.error( "Payment failed for order ##order.getId()", e )
            rethrow
        }
    }
}

Standalone Logger Access (No WireBox)

// Get logger by string category
var log = application.logbox.getLogger( "myapp.services.OrderService" )

// Get logger scoped to the current object (resolves to full CFC path)
var log = application.logbox.getLogger( this )

Performance: Avoid Unnecessary Log Evaluation

Problem — always evaluates the message

// BAD: the string interpolation runs even if DEBUG is disabled
log.debug( "User data: #serializeJSON( user )#" )

Solution 1 — can{} guard

if( log.canDebug() ) {
    log.debug( "User data: #serializeJSON( user )#" )
}

Solution 2 — Closure message (preferred for multi-line expressions)

// The closure is ONLY executed when the level is enabled
log.debug( () => "User data: #serializeJSON( user )#" )

log.debug( () => {
    var parts = []
    parts.append( "id=#user.getId()#" )
    parts.append( "email=#user.getEmail()#" )
    return parts.toList( ", " )
} )

Always use canDebug() or closure messages before any expensive serialization, query, or computation that exists solely for logging.

Structured extraInfo and $toString()

extraInfo accepts any value. Appenders serialize it using this algorithm:

1. Simple value → use as-is
2. Object with $toString() → call it and use the return string
3. Exception → serialize to JSON
4. Object without $toString() → serialize to XML
5. Struct / array / query → serialize to JSON

Implement $toString() on domain objects

class User {

    function $toString() {
        return "#getName()#,#getEmail()#,#getRole()#"
    }
}

component {
    function $toString() {
        return "#getName()#,#getEmail()#,#getRole()#"
    }
}

// When logged, calls user.$toString() automatically
log.debug( "User authenticated", user )

// Structured struct — serialized to JSON
log.error( "Checkout failed", {
    userId  : user.getId(),
    cart    : cart.getTotalItems(),
    error   : e.message
} )

Category Inheritance

Categories use dot-notation inheritance. When a logger for a.b.c is requested and not configured, LogBox walks up: a.b → a → root.

root           FATAL–DEBUG → console, file
└── models     INFO–DEBUG  → console
    └── models.UserService  DEBUG only → console   (explicitly configured)
    └── models.OrderService (NOT configured) → inherits from models: INFO–DEBUG → console

Example configuration:

categories = {
    // All models package — INFO and above
    "models" : { levelMin : "INFO", levelMax : "FATAL", appenders : "console" },

    // One specific model — DEBUG only
    "models.UserService" : { levelMin : "DEBUG", levelMax : "DEBUG", appenders : "console" }
}

models.OrderService is not configured → it inherits from models (INFO–FATAL, console). models.UserService is explicitly configured → DEBUG only, console.

Use package-level categories to toggle entire features without changing code.

Custom Appenders

Extend AbstractAppender (standalone: logbox.system.logging.AbstractAppender, ColdBox: coldbox.system.logging.AbstractAppender).

// BoxLang — models/logging/WebhookAppender.bx
class WebhookAppender extends coldbox.system.logging.AbstractAppender {

    function init( required string name, struct properties = {}, string layout = "", numeric levelMin = 0, numeric levelMax = 4 ) {
        super.init( argumentCollection = arguments )
        return this
    }

    // Called once when appender is registered — good for setup
    function onRegistration() {
        variables.webhookUrl = getProperty( "webhookUrl" )
        variables.minSeverity = getProperty( "minSeverity", "ERROR" )
    }

    // Called for every log event this appender receives
    function logMessage( required logEvent ) {
        if( !len( variables.webhookUrl ) ) return

        // Use hasCustomLayout() + getCustomLayout() for custom formatting
        var message = hasCustomLayout()
            ? getCustomLayout().format( logEvent )
            : "[#severityToString( logEvent.getSeverity() )#] #logEvent.getMessage()#"

        http url=variables.webhookUrl method="POST" throwOnError=false {
            httpparam type="header" name="Content-Type" value="application/json"
            httpparam type="body" value=serializeJSON( {
                severity  : severityToString( logEvent.getSeverity() ),
                category  : logEvent.getCategory(),
                message   : message,
                extraInfo : logEvent.getExtraInfo(),
                timestamp : logEvent.getTimestamp()
            } )
        }
    }

    function onUnRegistration() {}
}

// CFML equivalent
component extends="coldbox.system.logging.AbstractAppender" {

    function init( required string name, struct properties = {}, string layout = "", numeric levelMin = 0, numeric levelMax = 4 ) {
        super.init( argumentCollection = arguments )
        return this
    }

    function onRegistration() {
        variables.webhookUrl = getProperty( "webhookUrl" )
    }

    function logMessage( required logEvent ) {
        if( !len( variables.webhookUrl ) ) return
        cfhttp( url=variables.webhookUrl, method="POST", throwOnError=false ) {
            cfhttpparam( type="header", name="Content-Type", value="application/json" )
            cfhttpparam( type="body", value=serializeJSON( {
                severity : severityToString( logEvent.getSeverity() ),
                message  : logEvent.getMessage()
            } ) )
        }
    }

    function onUnRegistration() {}
}

AbstractAppender Helper Methods

Register a custom appender in config:

appenders = {
    webhook : {
        class      : "models.logging.WebhookAppender",
        levelMin   : "ERROR",
        levelMax   : "FATAL",
        properties : { webhookUrl : "https://hooks.example.com/alerts" }
    }
}

Custom Layouts

Extend AbstractLayout (standalone: logbox.system.logging.Layout, ColdBox: coldbox.system.logging.AbstractLayout). Implement one method: format( logEvent ).

// BoxLang — models/logging/JsonLayout.bx
class JsonLayout extends coldbox.system.logging.AbstractLayout {

    function format( required logEvent ) {
        return serializeJSON( {
            "@timestamp" : dateTimeFormat( logEvent.getTimestamp(), "yyyy-mm-dd'T'HH:nn:ssZ" ),
            level        : logEvent.getSeverity(),
            logger       : logEvent.getCategory(),
            message      : logEvent.getMessage(),
            extra        : logEvent.getExtraInfo()
        } )
    }
}

// CFML
component extends="coldbox.system.logging.AbstractLayout" {

    function format( required logEvent ) {
        return serializeJSON( {
            level    : logEvent.getSeverity(),
            logger   : logEvent.getCategory(),
            message  : logEvent.getMessage(),
            extra    : logEvent.getExtraInfo()
        } )
    }
}

Use a layout in appender config:

console : {
    class  : "coldbox.system.logging.appenders.ConsoleAppender",
    layout : "models.logging.JsonLayout"
}

LogEvent API

Production Best Practices

• Use logbox:logger:{this} — category automatically matches the class path, enabling inheritance control without code changes
• Guard expensive messages — always use canDebug() / closure messages before building data solely for logging
• Structure extraInfo as a struct — enables JSON appenders and log aggregators (ELK, Splunk, etc.) to parse fields
• Never log secrets — redact passwords, tokens, PII, and card numbers before passing them to any logger
• Development: root → DEBUG–FATAL → ConsoleAppender only (no file I/O overhead)
• Production: root → WARN–FATAL → RollingFileAppender; optionally FATAL → EmailAppender
• Category granularity: define a category per package (models, handlers, services) — not per class — for bulk toggling in config
• Use off array to silence noisy packages (e.g., third-party modules) without removing them from appender config
• Rolling file in production: set fileMaxSize : 5000 (5 MB) and fileMaxArchives : 5 to cap disk usage
• Async appenders (async : true) for high-throughput systems — be aware that async logging may lose entries on abrupt shutdown
• Custom appenders for third-party sinks (Slack, PagerDuty, CloudWatch): keep all transport logic inside the appender, never inline in services