Introduction to Yii message logging mechanism

adminYii0 Comment
5 min. reading

I needed a brief memo-like article, gathering most important information about Yii logging system. Here it is.

Message logging mechanism in Yii 1.x is available out of the box, but needs proper configuration to become enabled in your application. For details, read appropriate article in Yii 1.x guide.

General information

Message can be logged manually or automatically. All logs are stored in memory and dumped to configured log routes in onRequestEnd event.

Manual message log can be done using:

Yii::log($message, $level, $category);

Alternatively you can use

Yii::trace($message, $category);

which actually means the same as:

Yii::log($message, CLogger::LEVEL_TRACE, $category);

Trace-level messages (logged with CLogger::LEVEL_TRACE level) are stored only in debug mode.

Levels and categories

Other levels can be found either in Yii 1.x guide or directly in source code stored at GitHub.

The CLogger::LEVEL_PROFILE is a non-standard level for profiling only. You can read more about it in here.

Levels are used for two purposes:

  • to specify which messages are logged automatically and
  • to match level given in Yii::log() with given log router default error level.

So, for example, if CFileLogRoute.levels equals 'error' then this mean that this log router won’t store any other log message, except those with error level set.

If you want to turn off automatic logging for particular log route (i.e. use it only for manual logging) then you have to set your own level (e.g. custom). Do not confuse this with an empty string as, by default, setting router’s levels to empty string will log anything and using empty string as level in Yii::log() will revert it to default info value and log message under that level

Therefore, you must use 'levels'=>'custom' and Yii::log($message, 'custom', $category) in this scenario. More information on this behavior can be found at this Yii Forum post.

Categories and path aliases

Message category (path alias) corresponds to Yii root aliases. So, for example, setting 'categories'=>'system.*' will record only messages, that has system as $category set.

In most cases this setting is practical only when doing manual log.

For automatic logging routes, this shouldn’t be set. It should be set to default, empty array meaning to log messages with all categories.

Real-time logging

Sometimes your application crashes so badly, that Yii isn’t able to process onRequestEnd event, where it writes all logs and you end up with nothing.

If you want to work over such situations, you have to implement a real-time logging and use PHP’s core error_log function. There’s an article on Yii Wiki with a great examples on how to solve this.

Configuration example

Here is an entire example configuration of Yii 1.x logging system in one of application that may team has done:

'log'=>array
(
    'class'=>'CLogRouter',
    'routes'=>array
    (
        array
        (
            'class'=>'CFileLogRoute',
            'levels'=>'warning, error',
            'categories'=>'system.db.*'
        ),
        array
        (
            'class'=>'DbLogRoute',
            'connectionID'=>'db',
            'autoCreateLogTable'=>true,
            'levels'=>'info, warning, error, custom'
        )
    )
),

We’re using an enhanced (customized) database log route (DbLogRoute — see /protected/components/extenders) to log everything to database (excluding trace-level messages, but including manually logged information). It extends Yii’s default database logging mechanism, by adding user ID, request URL and user IP address logging, as described in this article.

Since this log route is used also for manual logging purposes, it uses ‘custom’ level, as described above.

A [CDbLogRoute.connectionID] is set to 'db' (default connection), because in base implementation of CDbLogRoute this isn’t assumed as default. If this isn’t set, a SQLite database would be created (which we want to avoid).

We’re also using CFileLogRoute for automatic logging of error and warning level messages, in system.db category. This is additional level of logging that might log some DB related errors, which most likely wouldn’t be logged using DbLogRoute.

It uses default set of options, which means, that messages will be logged to /protected/runtime/application.log. This file will have 1024 kbytes at most and when this limit is reached, it will be renamed, by adding .1 to the name, then .2, .3. Up to five files of such name pattern will be created. So — if total size of 5120 kbytes (5 MB) will be reached, Yii start to overwrite oldest log files.

Since we set this log route to log only error-level messages, this shouldn’t happen to quick.

Leave a Reply