runtime-logging.md 4.28 KB
Newer Older
1 2 3
Logging
=======

4
> Note: This section is under development.
Qiang Xue committed
5

6
Yii provides flexible and extensible logger that is able to handle messages according to severity level or their type.
7 8 9 10 11 12 13 14 15 16 17
You may filter messages by multiple criteria and forward them to files, email, debugger etc.

Logging basics
--------------

Basic logging is as simple as calling one method:

```php
\Yii::info('Hello, I am a test log message');
```

18 19 20
You can log simple strings as well as more complex data structures such as arrays or objects.
When logging data that is not a string the defaulf yii log targets will serialize the value using [[yii\helpers\Vardumper::export()]].

21 22 23 24 25 26 27 28 29 30
### Message category

Additionally to the message itself message category could be specified in order to allow filtering such messages and
handing these differently. Message category is passed as a second argument of logging methods and is `application` by
default.

### Severity levels

There are multiple severity levels and corresponding methods available:

31
- [[Yii::trace]] used maily for development purpose to indicate workflow of some code. Note that it only works in
32
  development mode when `YII_DEBUG` is set to `true`.
33
- [[Yii::error]] used when there's unrecoverable error.
34
- [[Yii::warning]] used when an error occurred but execution can be continued.
35
- [[Yii::info]] used to keep record of important events such as administrator logins.
36 37 38 39

Log targets
-----------

Saphronov Mark committed
40
When one of the logging methods is called, message is passed to [[yii\log\Logger]] component accessible as
Qiang Xue committed
41 42
`Yii::getLogger()`. Logger accumulates messages in memory and then when there are enough messages
or when the current request finishes, sends them to different log targets, such as file or email.
43 44 45 46 47

You may configure the targets in application configuration, like the following:

```php
[
48
    'bootstrap' => ['log'], // ensure logger gets loaded before application starts
49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67
    'components' => [
        'log' => [
            'targets' => [
                'file' => [
                    'class' => 'yii\log\FileTarget',
                    'levels' => ['trace', 'info'],
                    'categories' => ['yii\*'],
                ],
                'email' => [
                    'class' => 'yii\log\EmailTarget',
                    'levels' => ['error', 'warning'],
                    'message' => [
                        'to' => ['admin@example.com', 'developer@example.com'],
                        'subject' => 'New example.com log message',
                    ],
                ],
            ],
        ],
    ],
68 69 70
]
```

71
In the config above we are defining two log targets: [[yii\log\FileTarget|file]] and [[yii\log\EmailTarget|email]].
72 73
In both cases we are filtering messages handles by these targets by severity. In case of file target we're
additionally filter by category. `yii\*` means all categories starting with `yii\`.
74

75
Each log target can have a name and can be referenced via the [[yii\log\Logger::targets|targets]] property as follows:
76 77 78 79 80

```php
Yii::$app->log->targets['file']->enabled = false;
```

81 82
When the application ends or [[yii\log\Logger::flushInterval|flushInterval]] is reached, Logger will call
[[yii\log\Logger::flush()|flush()]] to send logged messages to different log targets, such as file, email, web.
83

Carsten Brandt committed
84
> Note: In the above configuration we added the log component to the list of [bootstrap](runtime-bootstrapping.md) components that
85 86
  get initialized when the application is initialized to ensure logging is enabled from the start.

87 88 89 90

Profiling
---------

91 92
Performance profiling is a special type of message logging that can be used to measure the time needed for the
specified code blocks to execute and find out what the performance bottleneck is.
93

94 95
To use it we need to identify which code blocks need to be profiled. Then we mark the beginning and the end of each code
block by inserting the following methods:
96

97 98 99 100 101 102 103 104 105 106 107 108
```php
\Yii::beginProfile('myBenchmark');
...code block being profiled...
\Yii::endProfile('myBenchmark');
```

where `myBenchmark` uniquely identifies the code block.

Note, code blocks need to be nested properly such as

```php
\Yii::beginProfile('block1');
109 110 111 112
    // some code to be profiled
    \Yii::beginProfile('block2');
        // some other code to be profiled
    \Yii::endProfile('block2');
113 114
\Yii::endProfile('block1');
```
115

116
Profiling results [could be displayed in debugger](module-debug.md).