Logging¶

Logging Configuration¶

Configuring Log should be done during your application’s bootstrap phase. The config/app.php file is intended for just this. You can define as many or as few loggers as your application needs. Loggers should be configured using Cake\Log\Log. An example would be:

use Cake\Log\Log;

// Short classname
Log::config('debug', [
    'className' => 'File',
    'path' => LOGS,
    'levels' => ['notice', 'info', 'debug'],
    'file' => 'debug',
]);

// Fully namespaced name.
Log::config('error', [
    'className' => 'Cake\Log\Engine\FileLog',
    'path' => LOGS,
    'levels' => ['warning', 'error', 'critical', 'alert', 'emergency'],
    'file' => 'error',
]);

The above creates two loggers. One named debug the other named error. Each is configured to handle different levels of messages. They also store their log messages in separate files, so it’s easy to separate debug/notice/info logs from more serious errors. See the section on Using Levels for more information on the different levels and what they mean.

Once a configuration is created you cannot change it. Instead you should drop the configuration and re-create it using Cake\Log\Log::drop() and Cake\Log\Log::config().

It is also possible to create loggers by providing a closure. This is useful when you need full control over how the logger object is built. The closure has to return the constructed logger instance. For example:

Log::config('special', function () {
    return new \Cake\Log\Engine\FileLog(['path' => LOGS, 'file' => 'log']);
});

Configuration options can also be provided as a DSN string. This is useful when working with environment variables or PaaS providers:

Log::config('error', [
    'url' => 'file:///?levels[]=warning&levels[]=error&file=error',
]);

// For src/Log
Log::config('otherFile', [
    'className' => 'Database',
    'model' => 'LogEntry',
    // ...
]);

// For plugin called LoggingPack
Log::config('otherFile', [
    'className' => 'LoggingPack.Database',
    'model' => 'LogEntry',
    // ...
]);

namespace App\Log\Engine;
use Cake\Log\Engine\BaseLog;

class DatabaseLog extends BaseLog
{
    public function __construct($options = [])
    {
        parent::__construct($options);
        // ...
    }

    public function log($level, $message, array $context = [])
    {
        // Write to the database.
    }
}

Error and Exception Logging¶

Errors and Exceptions can also be logged. By configuring the corresponding values in your app.php file. Errors will be displayed when debug is true and logged when debug is false. To log uncaught exceptions, set the log option to true. See Configuration for more information.

Interacting with Log Streams¶

You can introspect the configured streams with Cake\Log\Log::configured(). The return of configured() is an array of all the currently configured streams. You can remove streams using Cake\Log\Log::drop(). Once a log stream has been dropped it will no longer receive messages.

Using the FileLog Adapter¶

As its name implies FileLog writes log messages to files. The level of log message being written determines the name of the file the message is stored in. If a level is not supplied, LOG_ERR is used which writes to the error log. The default log location is logs/$level.log:

// Executing this inside a CakePHP class
$this->log("Something didn't work!");

// Results in this being appended to logs/error.log
// 2007-11-02 10:22:02 Error: Something didn't work!

The configured directory must be writable by the web server user in order for logging to work correctly.

You can configure additional/alternate FileLog locations when configuring a logger. FileLog accepts a path which allows for custom paths to be used:

Log::config('custom_path', [
    'className' => 'File',
    'path' => '/path/to/custom/place/'
]);

Logging to Syslog¶

In production environments it is highly recommended that you setup your system to use syslog instead of the files logger. This will perform much better as any writes will be done in a (almost) non-blocking fashion and your operating system logger can be configured separately to rotate files, pre-process writes or use a completely different storage for your logs.

Using syslog is pretty much like using the default FileLog engine, you just need to specify Syslog as the engine to be used for logging. The following configuration snippet will replace the default logger with syslog, this should be done in the bootstrap.php file:

Log::config('default', [
    'engine' => 'Syslog'
]);

The configuration array accepted for the Syslog logging engine understands the following keys:

• format: An sprintf template string with two placeholders, the first one for the error level, and the second for the message itself. This key is useful to add additional information about the server or process in the logged message. For example: %s - Web Server 1 - %s will look like error - Web Server 1 - An error occurred in this request after replacing the placeholders.

• prefix: An string that will be prefixed to every logged message.

• flag: An integer flag to be used for opening the connection to the logger, by default LOG_ODELAY will be used. See openlog documentation for more options

• facility: The logging slot to use in syslog. By default LOG_USER is used. See syslog documentation for more options

Writing to Logs¶

Writing to the log files can be done in 2 different ways. The first is to use the static Cake\Log\Log::write() method:

Log::write('debug', 'Something did not work');

The second is to use the log() shortcut function available on any class using the LogTrait. Calling log() will internally call Log::write():

// Executing this inside a class using LogTrait
$this->log("Something did not work!", 'debug');

All configured log streams are written to sequentially each time Cake\Log\Log::write() is called. If you have not configured any logging adapters log() will return false and no log messages will be written.

// Configure logs/shops.log to receive all levels, but only
// those with `orders` and `payments` scope.
Log::config('shops', [
    'className' => 'File',
    'path' => LOGS,
    'levels' => [],
    'scopes' => ['orders', 'payments'],
    'file' => 'shops.log',
]);

// Configure logs/payments.log to receive all levels, but only
// those with `payments` scope.
Log::config('payments', [
    'className' => 'File',
    'path' => LOGS,
    'levels' => [],
    'scopes' => ['payments'],
    'file' => 'payments.log',
]);

Log::warning('this gets written only to shops.log', ['scope' => ['orders']]);
Log::warning('this gets written to both shops.log and payments.log', ['scope' => ['payments']]);

Log::warning('This is a warning', ['orders']);
Log::warning('This is a warning', 'payments');

Log API¶

class Cake\Log\Log¶

A simple class for writing to logs.

static Cake\Log\Log::config($key, $config)¶

Parameters

• $name (string) – Name for the logger being connected, used to drop a logger later on.

• $config (array) – Array of configuration information and constructor arguments for the logger.

Get or set the configuration for a Logger. See Logging Configuration for more information.

static Cake\Log\Log::configured¶

Returns

An array of configured loggers.

Get the names of the configured loggers.

static Cake\Log\Log::drop($name)¶

Parameters

• $name (string) – Name of the logger you wish to no longer receive messages.

static Cake\Log\Log::write($level, $message, $scope = [])¶

Write a message into all the configured loggers. $level indicates the level of log message being created. $message is the message of the log entry being written to. $scope is the scope(s) a log message is being created in.

static Cake\Log\Log::levels¶

Call this method without arguments, eg: Log::levels() to obtain current level configuration.

Logging Trait¶

trait Cake\Log\LogTrait¶

A trait that provides shortcut methods for logging

Cake\Log\LogTrait::log($msg, $level = LOG_ERR)¶

Log a message to the logs. By default messages are logged as ERROR messages. If $msg isn’t a string it will be converted with print_r before being logged.

Using Monolog¶

Monolog is a popular logger for PHP. Since it implements the same interfaces as the CakePHP loggers, it is easy to use in your application as the default logger.

After installing Monolog using composer, configure the logger using the Log::config() method:

// config/bootstrap.php

use Monolog\Logger;
use Monolog\Handler\StreamHandler;

Log::config('default', function () {
    $log = new Logger('app');
    $log->pushHandler(new StreamHandler('path/to/your/combined.log'));
    return $log;
});

// Optionally stop using the now redundant default loggers
Log::drop('debug');
Log::drop('error');

Use similar methods if you want to configure a different logger for your console:

// config/bootstrap_cli.php

use Monolog\Logger;
use Monolog\Handler\StreamHandler;

Log::config('default', function () {
    $log = new Logger('cli');
    $log->pushHandler(new StreamHandler('path/to/your/combined-cli.log'));
    return $log;
});

// Optionally stop using the now redundant default CLI loggers
Configure::delete('Log.debug');
Configure::delete('Log.error');