LogBox : Enterprise Logging & Messaging
7.x
7.x
  • Introduction
    • Contribution Guide
    • Release History
      • What's New With 7.2.0
      • What's New With 7.1.0
      • What's New With 7.0.0
    • Upgrading to LogBox 7
    • About This Book
      • Author
  • Getting Started
    • Features at a Glance
    • Installation
      • LogBox Refcard
    • Need For Logging
    • How Does LogBox Work?
      • LogBox
      • Appender
      • Logger
        • Logger Category Inheritance
        • Security Levels
        • Dynamic Appenders
      • Layout
  • Configuration
    • Configuring LogBox
      • LogBox DSL
      • Adding Appenders
      • Adding Categories to Specific Logging Levels
      • Adding Categories Granularly
      • Configuring The Root Logger
  • Usage
    • Using LogBox
    • Using a Logger Object
      • When To Log
      • ExtraInfo Serialization
    • Appender Properties
      • CFAppender
      • ConsoleAppender
      • DBAppender
      • EmailAppender
      • FileAppender
      • RollingFileAppender
      • ScopeAppender
      • SocketAppender
      • TraceAppender
    • LogBox in a ColdBox Application
      • Configuration Within ColdBox
      • Benefits of using LogBox in a ColdBox application
      • Where is LogBox stored in a ColdBox app?
      • LogBox from the ColdBox Proxy
      • The LogBox Injection DSL
  • Extending LogBox
    • Creating Custom Appenders
      • Helper Methods
      • Instance Members
      • Dealing With Custom Layouts
      • Registering Appenders at Runtime
    • Creating a Custom Layout
      • Instance Members
Powered by GitBook
On this page
  • Base Config
  • Appenders
  • Root Logger
  • Categories

Was this helpful?

Edit on GitHub
Export as PDF
  1. Configuration
  2. Configuring LogBox

LogBox DSL

As we have seen the LogBox DSL can be used in different contexts:

  • Portable CFC with a configure() method in a logbox variable

  • ColdBox config inside the configure() method in a logbox variable

  • A struct literal sent in to the constructor of LogBox

NO matter how you dice it, it's the same LogBox Config DSL:

**
* A LogBox configuration data object
*/
component{

    function configure(){
        logBox = {
            
            appenders : {},
            
            root : {},
            
            categories : {},
            
            fatal : [],
            error : [],
            warn  : [],
            info  : [],
            debug : [],
            off   : []

        };
    }
}

Base Config

Root level configuration keys.

Key

Description

appenders

A structure where you will define appenders

root

A structure where you will configure the root logger

categories

A structure where you can define granular categories (OPTIONAL)

DEBUG

An array that will hold all the category names to place under the DEBUG logging level (OPTIONAL)

INFO

An array that will hold all the category names to place under the INFO logging level (OPTIONAL)

WARN

An array that will hold all the category names to place under the WARN logging level (OPTIONAL)

ERROR

An array that will hold all the category names to place under the ERROR logging level (OPTIONAL)

FATAL

An array that will hold all the category names to place under the FATAL logging level (OPTIONAL)

OFF

An array that will hold all the category names to not log at all (OPTIONAL)

Appenders

appenders : {

    console: { class : "ConsoleAppender" },
    
    jsonConsole : {
        class : "ConsoleAppender",
        layout : "models.JSONLayout",
        levelMin : 0,
        levelMax : 4
    },
    
    errorLog: { 
        class: "FileAppender",
        properties: {
            filePath : "/logs",
            fileName : "appname-errors"     
        },
        levelMin : "FATAL",
        levelMax : "ERROR"
    }
}

To define an appender you must define a struct with a key value which is the internal name of the appender. Each appender's name must be unique. You configure each appender with the following keys:

Key
Description

class

The class path of the appender

properties

The properties struct for the appender (OPTIONAL)

layout

The layout class path of the layout object to use (OPTIONAL)

levelMin

The numerical or English word of the minimal logging level (OPTIONAL, defaults to 0 [FATAL])

levelMax

The numerical or English word of the maximum logging level (OPTIONAL, defaults to 4 [DEBUG])

Root Logger

To configure the root logger, use the following keys:

root : {
    levelMax : "INFO",
    appenders : "*"
}

root : {
    appenders : "console",
    levelMax : "DEBUG"
}

Key

Description

levelMin

The numerical or English word of the minimal logging level (OPTIONAL, defaults to 0 [FATAL])

levelMax

The numerical or English word of the maximum logging level (OPTIONAL, defaults to 4 [DEBUG])

appenders

A string list of the appenders to use for logging or the * convention for all appenders.

exclude

A string list of appenders to exclude from logging.

Categories

// Granualr Categories
categories={
    "coldbox.system" = { levelMin="FATAL", levelMax="INFO", appenders="*" },
    "model.security" = { levelMax="DEBUG", appenders="console" }
}

To define categories, you define a struct with a key value, which is the internal name of the category. Each category name must be unique,. You configure each category with the following keys:

Key

Description

levelMin

The numerical or English word of the minimal logging level (OPTIONAL, defaults to 0 [FATAL])

levelMax

The numerical or English word of the maximum logging level (OPTIONAL, defaults to 4 [DEBUG])

appenders

A string list of the appenders to use for logging (OPTIONAL, defaults to *)

exclude

A string list of appenders to exclude from logging.

As you might notice, the names of the keys on all the structures match 100% to the programmatic methods you can also use to configure logBox. So, when in doubt, refer back to the argument names.

Example Configuration

logBox = {
    // Appenders
    appenders = {
        appenderName = {
            class="class.to.appender",
            layout="class.to.layout",
            levelMin=0,
            levelMax=4,
            properties={
                name  = value,
                prop2 = value 2
            }
    },
    // Root Logger
    root = { levelMin="FATAL", levelMax="DEBUG", appenders="*" },
    // Granualr Categories
    categories={
        "coldbox.system" = { levelMin="FATAL", levelMax="INFO", appenders="*" },
        "model.security" = { levelMax="DEBUG", appenders="console" }
    },
    // Implicit categories
    debug = [ "coldbox.system.interceptors"  ],
    info  = [ "model.class", "model2.class2" ],
    warn  = [ "model.class", "model2.class2" ],
    error = [ "model.class", "model2.class2" ],
    fatal = [ "model.class", "model2.class2" ],
    off   = [ "model.class", "model2.class2" ]
};
PreviousConfiguring LogBoxNextAdding Appenders

Last updated 11 months ago

Was this helpful?