> For the complete documentation index, see [llms.txt](https://logbox.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://logbox.ortusbooks.com/configuration/configuring-logbox/logbox-dsl.md).

# LogBox DSL

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

* Portable class 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:

{% tabs %}
{% tab title="BoxLang" %}

```js
**
* A LogBox configuration data object
*/
class{

    function configure(){
        logBox = {

            appenders : {},

            root : {},

            categories : {},

            fatal : [],
            error : [],
            warn  : [],
            info  : [],
            debug : [],
            off   : []

        };
    }
}
```

{% endtab %}

{% tab title="CFML" %}

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

    function configure(){
        logBox = {

            appenders : {},

            root : {},

            categories : {},

            fatal : [],
            error : [],
            warn  : [],
            info  : [],
            debug : [],
            off   : []

        };
    }
}
```

{% endtab %}
{% endtabs %}

## Base Config

Root level configuration keys.

<table data-header-hidden><thead><tr><th width="224">Key</th><th>Description</th></tr></thead><tbody><tr><td>Key</td><td>Description</td></tr><tr><td><code>appenders</code></td><td>A structure where you will define appenders</td></tr><tr><td><code>root</code></td><td>A structure where you will configure the root logger</td></tr><tr><td><code>categories</code></td><td>A structure where you can define granular categories (OPTIONAL)</td></tr><tr><td><code>DEBUG</code></td><td>An array that will hold all the category names to place under the DEBUG logging level (OPTIONAL)</td></tr><tr><td><code>INFO</code></td><td>An array that will hold all the category names to place under the INFO logging level (OPTIONAL)</td></tr><tr><td><code>WARN</code></td><td>An array that will hold all the category names to place under the WARN logging level (OPTIONAL)</td></tr><tr><td><code>ERROR</code></td><td>An array that will hold all the category names to place under the ERROR logging level (OPTIONAL)</td></tr><tr><td><code>FATAL</code></td><td>An array that will hold all the category names to place under the FATAL logging level (OPTIONAL)</td></tr><tr><td><code>OFF</code></td><td>An array that will hold all the category names to not log at all (OPTIONAL)</td></tr><tr><td><code>serializeExtraInfo</code></td><td>Boolean (default: <code>true</code>). When <code>true</code>, complex objects passed as <code>extraInfo</code> are automatically serialized to a string representation when logging. Set to <code>false</code> to skip serialization. (OPTIONAL)</td></tr></tbody></table>

### Appenders

```javascript
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:

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

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

<table data-header-hidden><thead><tr><th width="148">Key</th><th>Description</th></tr></thead><tbody><tr><td>Key</td><td>Description</td></tr><tr><td><code>levelMin</code></td><td>The numerical or English word of the minimal logging level (OPTIONAL, defaults to 0 [FATAL])</td></tr><tr><td><code>levelMax</code></td><td>The numerical or English word of the maximum logging level (OPTIONAL, defaults to 4 [DEBUG])</td></tr><tr><td><code>appenders</code></td><td>A string list of the appenders to use for logging or the <code>*</code> convention for all appenders.</td></tr><tr><td><code>exclude</code></td><td>A string list of appenders to exclude from logging.</td></tr></tbody></table>

### Categories

```cfscript
// 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:

<table data-header-hidden><thead><tr><th width="152">Key</th><th>Description</th></tr></thead><tbody><tr><td>Key</td><td>Description</td></tr><tr><td><code>levelMin</code></td><td>The numerical or English word of the minimal logging level (OPTIONAL, defaults to 0 [FATAL])</td></tr><tr><td><code>levelMax</code></td><td>The numerical or English word of the maximum logging level (OPTIONAL, defaults to 4 [DEBUG])</td></tr><tr><td><code>appenders</code></td><td>A string list of the appenders to use for logging (OPTIONAL, defaults to *)</td></tr><tr><td><code>exclude</code></td><td>A string list of appenders to exclude from logging.</td></tr></tbody></table>

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

```javascript
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" ]
};
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://logbox.ortusbooks.com/configuration/configuring-logbox/logbox-dsl.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.