Application Environments and Logging

The ability to log messages of various importance, along with context information, aids immensely in debugging on environments in which you have no control, or after a bug has occurred and cannot be reproduced.

To this end, the Totsy_Core module provides enhanced logging capabilities using the third-party Monolog library, which supports logging to a variety of locations. This module also provides the ability to determine the type of local runtime environment, declared in the app/etc/local.xml file.

Logging is performed by calling a function, named for the log record's importance level, on a logger object. A logger implements the interface defined by Totsy_Core_Model_LoggerInterface. Currently, only two such implementations are supported:

1. Totsy_Core_Model_Logger_MageLogger which sends all log records to the Magento built-in logging functionality, and

2. Totsy_Core_Model_Logger_MonologLogger which sends all log records to a configured Monolog\Logger object.

An instance of either of these classes is created and returned by a Logger helper in the Totsy_Core module. This helper accepts the name of a configurable logger (which can be configured in a Magento XML configuration file) and selects the appropriate Logger implementation to use.

If the Monolog library is available (in lib/vendor/monolog), then a Totsy_Core_Model_Logger_MonologLogger object will be created, configured and returned. Otherwise, the default Totsy_Core_Model_Logger_MageLogger will be used instead, which effectively guarantees a logger object, but tries to provide the better Monolog logger wherever possible.

Configuring Loggers

A logger object is named, and can be configured by name in the app/etc/local.xml file:

<loggers>
    <special><!-- The root element is the name of the logger -->
        <handlers><!-- At least one handler must be supplied -->
            <stream filename="var/log/special.log"><!-- 'stream' handlers output to a file -->
                <level><!-- Specify a logging threshold for any environments this handler is used on -->
                    <dev>DEBUG</dev>
                    <stg>INFO</stg>
                    <prd>ERR</prd>
                </level>
            </stream>
            <chrome><!-- 'chrome' handlers output to the ChromePHP browser extension -->
                <level>
                    <dev>DEBUG</dev>
                    <stg>INFO</stg>
                </level>
            </chrome>
        </handlers>
    </special>
</loggers>

Logging in Application Code

Once your loggers have been configured in the Magento configuration, you can obtain a logger object from the Logger helper by name:

$logger = Mage::helper('core/logger')->getLogger('special');
$logger->debug("A new logger is born.");

Logging is encouraged everywhere possible. An average of one logging statement for every 5 lines of code is desired. There is a negligible performance cost for these calls when logs are not actually recorded (i.e. low-level log messages, such as DEBUG and INFO should never be recorded in a production environment), but there is a high value for these log messages in development and testing environments.

Application Environments

The environment that the web application is running in should be declared in the app/etc/local.xml file inside the global/config element:

<environment>stg</environment>

The supported values for this tag are dev (Development), stg (Staging), and prd (Production). This environment configuration is used to determine the log level threshold for handlers in a Monolog Logger object.

Recommended Reading

Read the Monolog documentation to understand how handlers work (since the order of declared handlers is important) in order to obtain the correct logging setup, that will log the right amount of information, to the right places, in each environment.