#

# Example: YUI Configuration to Filter Log Messages

This example illustrates how to configure your YUI instance to ignore certain log messages to aid in reducing the signal-to-noise ratio when debugging.

Log messages filtered out from the YUI config are permanently ignored. If you want to be able to temporarily hide and reshow messages, use the ConsoleFilters plugin. It is not uncommon to set up `logInclude` or `logExclude` in the YUI configuration and use the ConsoleFilters plugin.

Log messages can be ignored based on the source (e.g. `event` or `attribute`) or based on their log level (info, warn, error).

#### Source filter

`sourceA` `sourceB` `sourceC`

#### Log level

info warn error

#### Log a message

log message

Source: A B C Category: info warn error

#### Code preview

    // YUI instance configuration
        var Y = YUI({
            "logLevel": "info",
            "logExclude": {
                "sourceC": true
            }
        });

        // Log statement
        Y.log("This is a log message!", "info", "sourceA");

### Setting up filters in the YUI configuration

The configuration object passed to the YUI constructor supports a few settings that can help manage Console output while debugging. These configuration options are `logExclude`, `logInclude`, `logLevel`, `filter`, and `filters`.

This example will show the use of the `logInclude`, `logExclude`, and `logLevel` configurations.

An example configuration might look like this:

    YUI({
        filter : 'debug', // request -debug versions of modules for log statements
        logExclude : {
            event : true,     // Don't broadcast log messages from the event module
            attribute : true, // or the attribute module
            widget : true     // or the widget module
        },
        logLevel : 'error',       // Show only errors in the Console
        useBrowserConsole : false // Don't use the browser's native console
    }).use('overlay','anim','console', function (Y) {

    /* Console instances will default to logLevel = "info" */

    });

`logExclude` and `logInclude` prevent the logging subsystem from broadcasting filtered log messages. `logLevel`, on the other hand is used by Console instances to filter messages received from the subsystem.

Updating `Y.config.logExclude` or `Y.config.logInclude` at runtime will immediately change the subsystem filtering, but will not recover messages previously sent from that source.

    YUI({
        logExclude : {
            event : true
        }
    }).use('console', function (Y) {

    /* In here, Y.config refers to the config object passed to the constructor */

    // Stop broadcasting log messages from the attribute module
    Y.config.logExclude.attribute = true;

    // Start broadcasting log messages from the event module again
    delete Y.config.logExclude.event;

    });

When a Console is instantiated, barring explicit `logLevel` attribute configuration, the `logLevel` will be adopted from the YUI instance's configured `logLevel`, or `Y.Console.LOG_LEVEL_INFO` ("info") as a fallback. Unlike `logExclude`, changing the value in the YUI configuration will only affect instantiated Consoles from that point on. Additionally, you can manually override the `logLevel` a Console instance will display by updating its `logLevel` attribute.

    YUI({ logLevel : "warn" }).use('console', function (Y) {

    var yconsole_1 = new Y.Console(); // logLevel == "warn"

    var yconsole_2 = new Y.Console({
        logLevel : "info" // override at construction
    });

    // This will not affect yconsole_1 or yconsole_2
    Y.config.logLevel = "error";

    var yconsole_3 = new Y.Console(); // logLevel == "error"

    yconsole_1.set("logLevel", "info"); // update this instance

    });

The interactive portion of this example illustrates the effect of various filter settings against logged messages. In a real application, it is most likely that the logging configuration won't be changed at runtime but set once in the YUI configuration at construction.

The most relevant portion of the code for the demo above is the updating of the YUI config and Console attribute.

    // Create and render the Console
    var yconsole = new Y.Console({
        boundingBox: '#console', // anchored to the page for the demo
        style: "block"
    }).render();

    ...

    // Source include or exclude select
    Y.on("change", function () {
        if (this.get("value") === "logInclude") {
            Y.config.logInclude = Y.config.logExclude;
            delete Y.config.logExclude;
        } else {
            Y.config.logExclude = Y.config.logInclude;
            delete Y.config.logInclude;
        }
        updatePreview();
    }, "#incexc");

    // These functions are called from a delegated event handler.
    // See the Full Code Listing for how they are called.
    function updateSourceFilters(source, checked) {
        var disposition = Y.one("#incexc").get("value"),
            cfg = Y.config[disposition]; // Y.config.logInclude or logExclude

        if (checked) {
            if (!cfg) {
                cfg = Y.config[disposition] = {};
            }
            cfg[source] = true; // e.g. Y.config.logInclude.sourceA = true;
        } else {
            delete cfg[source];

            if (!Y.Object.size(cfg)) {
                delete Y.config[disposition];
            }
        }

        updatePreview();
    }

    function updateLogLevel(level, checked) {
        if (checked) {
            Y.config.logLevel = level;
            yconsole.set("logLevel", level);
            updatePreview();
        }
    }

### Full Code Listing

#### Markup

    <form>
        <div id="demo" class="yui3-skin-sam">
            <div id="console"></div>

            <div class="filter-controls">
                <h4>Source filter</h4>
                <p>
                    <select id="incexc">
                        <option value="logExclude" selected="selected">Exclude</option>
                        <option value="logInclude">Include</option>
                    </select>
                    <label for="filter_a"><input type="checkbox" name="src_filter" value="sourceA" id="filter_a"> <code>sourceA</code></label>
                    <label for="filter_b"><input type="checkbox" name="src_filter" value="sourceB" id="filter_b"> <code>sourceB</code></label>
                    <label for="filter_c"><input type="checkbox" name="src_filter" value="sourceC" id="filter_c" checked="checked"> <code>sourceC</code></label>
                </p>
            </div>

            <div class="filter-controls">
                <h4>Log level</h4>
                <p>
                    <label for="lvl_info">
                        <input type="radio" name="log_level" id="lvl_info" value="info" checked="checked">
                        info
                    </label>
                    <label for="lvl_warn">
                        <input type="radio" name="log_level" id="lvl_warn" value="warn">
                        warn
                    </label>
                    <label for="lvl_error">
                        <input type="radio" name="log_level" id="lvl_error" value="error">
                        error
                    </label>
                </p>
            </div>

            <div class="form">
                <h4>Log a message</h4>
                <div>
                    <input type="text" id="msg" value="This is a log message!">
                    <input type="submit" id="log">log message</button>

                    <p>
                        Source:
                        <label for="msg_src_a">
                            <input type="radio" name="msg_src" id="msg_src_a" value="sourceA" checked="checked">
                            A
                        </label>
                        <label for="msg_src_b">
                            <input type="radio" name="msg_src" id="msg_src_b" value="sourceB">
                            B
                        </label>
                        <label for="msg_src_c">
                            <input type="radio" name="msg_src" id="msg_src_c" value="sourceC">
                            C
                        </label>

                        <span>Category:</span>
                        <label for="msg_info">
                            <input type="radio" name="msg_cat" id="msg_info" value="info" checked="checked">
                            info
                        </label>
                        <label for="msg_warn">
                            <input type="radio" name="msg_cat" id="msg_warn" value="warn">
                            warn
                        </label>
                        <label for="msg_error">
                            <input type="radio" name="msg_cat" id="msg_error" value="error">
                            error
                        </label>
                    </p>
                </div>

                <h4>Code preview</h4>
                <pre id="preview">// YUI instance configuration
        var Y = YUI({
            "logLevel": "info",
            "logExclude": {
                "sourceC": true
            }
        });

        // Log statement
        Y.log(&quot;This is a log message!&quot;, &quot;info&quot;, &quot;sourceA&quot;);</pre>
            </div>
        </div>
    </form>

#### JavaScript

    <script type="text/javascript">
    YUI().use("console", "selector-css3", "json-stringify", function (Y) {

    // Add the default filtering of sourceC messages
    Y.config.logExclude = {
        sourceC : true
    };

    // Create and render the Console
    var yconsole = new Y.Console({
        boundingBox: "#console",
        style: "block"
    }).render();

    // Set up event listeners
    // Source include or exclude select
    Y.on("change", function () {
        if (this.get("value") === "logInclude") {
            Y.config.logInclude = Y.config.logExclude;
            delete Y.config.logExclude;
        } else {
            Y.config.logExclude = Y.config.logInclude;
            delete Y.config.logInclude;
        }
        updatePreview();
    }, "#incexc");

    // delegate all checkbox and radio group clicks via a single event subscriber
    // routing to the appropriate function based on the input name
    var clickHandlers = {
        src_filter : updateSourceFilters,
        log_level  : updateLogLevel,
        msg_src    : updatePreview,
        msg_cat    : updatePreview
    };

    Y.delegate("click", function (e) {
        var input   = e.currentTarget,
            handler = clickHandlers[ input.get("name") ];

        if (handler) {
            handler(input.get("value"), input.get("checked"));
        }

    }, "#demo", "input[name]");

    // Log message input and radio groups
    Y.on("keyup", updatePreview, "#msg");

    // Log message button
    Y.on("click", function (e) {
        var msg = Y.one("#msg").get("value"),
            cat = Y.one("#demo input[name=msg_cat]:checked").get("value"),
            src = Y.one("#demo input[name=msg_src]:checked").get("value");

        Y.log(msg,cat,src);
        e.preventDefault(); // Don't submit the form
    }, "#log");

    // Support functions
    function updateSourceFilters(source, checked) {
        var disposition = Y.one("#incexc").get("value"),
            cfg = Y.config[disposition]; // Y.config.logInclude or logExclude

        if (checked) {
            if (!cfg) {
                cfg = Y.config[disposition] = {};
            }
            cfg[source] = true;
        } else {
            delete cfg[source];
            if (!Y.Object.size(cfg)) {
                delete Y.config[disposition];
            }
        }

        updatePreview();
    }

    function updateLogLevel(level, checked) {
        if (checked) {
            Y.config.logLevel = level;
            yconsole.set("logLevel", level);
            updatePreview();
        }
    }

    function updatePreview() {
        var filters   = Y.all("#demo input[name=src_filter]:checked"),
            cfg = {
                logLevel: Y.one("#demo input[name=log_level]:checked").get("value")
            };

        if (filters.size()) {
            cfg[Y.one("#incexc").get("value")] = Y.Array.hash(filters.get("value"));
        }

        Y.one("#preview").set("text",Y.Lang.sub(
            "// YUI instance configuration\n" +
            "var Y = YUI({cfg});\n\n" +
            "// Log statement\n" +
            'Y.log("{msg}", "{lvl}", "{src}");',
            {
                cfg: Y.JSON.stringify(cfg, null, 4),
                msg: Y.one("#msg").get("value"),
                lvl: Y.one("#demo input[name=msg_cat]:checked").get("value"),
                src: Y.one("#demo input[name=msg_src]:checked").get("value")
            }));
    }

    });
    </script>

#### CSS

    <style scoped>
    #console {
        float: left;
    }
    #demo .yui3-console .yui3-console-title {
        border: 0 none;
        color: #000;
        font-size: 13px;
        font-weight: bold;
        margin: 0;
        text-transform: none;
    }

    #demo .yui3-console .yui3-console-entry-meta {
        margin: 0;
    }

    .filter-controls p label {
        display: block;
        margin: .25em 0;
    }
    #demo input {
        vertical-align: middle;
    }

    .form {
        clear: left;
        padding: 1em 0;
    }

    .form span {
        padding-left: 3em;
    }

    #msg {
        width: 50%;
    }

    .filter-controls {
        width: 180px;
        margin-left: 1em;
        float: left;
    }

    #preview {
        background: #eee;
        border: 1px solid #999;
        margin: 1em 0;
        overflow: auto;
        padding: 1em;
        width: 480px;
    }
    </style>