From b79f38215780d319a8d81c280c2a3ea68a83d8b8 Mon Sep 17 00:00:00 2001
From: Alexander Makarov <sam@rmcreative.ru>
Date: Sun, 15 Dec 2013 22:13:39 +0100
Subject: [PATCH] Started docs about logger

---
 docs/guide/logging.md | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 83 insertions(+), 1 deletion(-)

diff --git a/docs/guide/logging.md b/docs/guide/logging.md
index ce14742..08175b8 100644
--- a/docs/guide/logging.md
+++ b/docs/guide/logging.md
@@ -1,5 +1,87 @@
 Logging
 =======
 
+Yii provides flexible and extensible logger that is able to handle messages according to serverity level or their type.
+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');
+```
+
+### 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:
+
+- `\Yii::trace` used maily for development purpose to indicate workflow of some code. Note that it only works in
+  development mode when `YII_DEBUG` is set to `true`.
+- `\Yii::error` used when there's unrecoverable error.
+- `\Yii::warning` used when an error occured but execution can be continued.
+- `\Yii::info` used to keep record of important events such as administrator logins.
+
+Log targets
+-----------
+
+When one of the logging methods is called, message is passed to `\yii\log\Logger` component also accessible as
+`Yii::$app->log`. Logger accumulates messages in memory and then when there are enough messages or when current
+request finishes, sends them to different log targets, such as file or email.
+
+You may configure the targets in application configuration, like the following:
+
+```php
+[
+	'components' => [
+		'log' => [
+			'targets' => [
+				'file' => [
+					'class' => 'yii\log\FileTarget',
+					'levels' => ['trace', 'info'],
+					'categories' => ['yii\*'],
+				],
+				'email' => [
+					'class' => 'yii\log\EmailTarget',
+					'levels' => ['error', 'warning'],
+					'emails' => ['admin@example.com'],
+				],
+			],
+		],
+	],
+]
+```
+
+In the config above we are defining two log targets: file and email. 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\`.
+
+Each log target can have a name and can be referenced via the [[targets]] property as follows:
+
+```php
+Yii::$app->log->targets['file']->enabled = false;
+```
+
+When the application ends or [[flushInterval]] is reached, Logger will call [[flush()]] to send logged messages to
+different log targets, such as file, email, Web.
+
+
+Configuring context information
+-------------------------------
+
+Profiling
+---------
+
+TBD
+
+- [[Yii::beginProfile()]]
+- [[Yii::endProfile()]]
+
 
-TDB
\ No newline at end of file