Author: Peter Keung
Date: 2007-01-25 21:33:13 +0100 (Thu, 25 Jan 2007)
New Revision: 4583
Log:
Edited EventLog eZ Component tutorial
Modified:
trunk/EventLog/docs/tutorial.txt
trunk/EventLog/docs/tutorial_auto_variables.php
trunk/EventLog/docs/tutorial_multiple_log_files.php
Modified: trunk/EventLog/docs/tutorial.txt
===================================================================
--- trunk/EventLog/docs/tutorial.txt 2007-01-25 15:55:22 UTC (rev 4582)
+++ trunk/EventLog/docs/tutorial.txt 2007-01-25 20:33:13 UTC (rev 4583)
@@ -1,4 +1,4 @@
-eZ components - EventLog
+eZ Components - EventLog
~~~~~~~~~~~~~~~~~~~~~~~~
.. contents:: Table of Contents
@@ -6,66 +6,65 @@
Introduction
============
-The EventLog component provides an API to log events and audit trails. These
-events and audit trails are written to files or other storage spaces in
-various formats. How and where the log messages (events and audit trails) are
-written depends on the chosen or customized log writer.
+The EventLog component provides an API to log events and audit trails with log
+messages. These log messages are written to files or other storage elements.
+How and where the log messages are written depends on the log writer.
The available log writers are:
-- ezcLogUnixFileWriter, which writes log messages to a file in an 'Unix' file
+- ezcLogUnixFileWriter, which writes log messages to a file in a *Unix* file
format.
-- ezcLogDatabaseWriter, which writes log messages to the database. Available
- in the EventLogDatabaseTieIn_ component.
+- ezcLogDatabaseWriter, which writes log messages to the database. This is
+ available in the EventLogDatabaseTieIn_ component.
Each of these writers can be customized or extended.
-An incoming log message can be written to zero or more writers. The writers
-that write the log message depends on the variables of the log message itself
and the
-ezcLogMapper implementation. An implementation of the ezcLogMapper checks the
-severity, source, and category from the log message and forwards the message
-to the matching writers.
+An incoming log message can be written with zero or more writers. The writers
+depend on the variables of the log message itself and the
+ezcLogMapper implementation. ezcLogMapper checks the
+severity, source and category from the log message and forwards the message
+to the appropriate writers.
Class overview
==============
-The following classes are most important to use, customize, or extend:
+The following classes are most important to use, customize or extend:
ezcLog
- The ezcLog is a singleton, meaning that only one instance to the log can
+ The ezcLog class is a singleton, meaning that only one instance of it can
exist. This class provides methods to configure and record log messages. The
- recorded log messages are sent to an implementation of the ezcLogMapper,
- deciding which writers should write the log message.
+ recorded log messages are sent to an implementation of ezcLogMapper, which
+ forwards the messages to the appropriate log writers.
ezcLogMapper
- The ezcLogMapper provides an interface for the log message mapping. Log
- messages are dispatched from the ezcLog to a writer. To which writer a
- message is dispatched is determined in the class that implements
- ezclogMapper and is assigned in the ezcLog.
+ ezcLogMapper provides an interface for log message mapping. Log
+ messages are dispatched from ezcLog to a writer. The particular writer is
+ determined in the class that implements
+ ezcLogMapper and is assigned in ezcLog.
ezcLogFilterSet
- The ezcLogFilterSet is an implementation of the ezcLogMapper. The
- ezcLogFilterSet contains a set of ezcLogFilterRules. These rules are
- processed sequentially. The rule assigned first will be processed first.
- Each rule determines whether the log message matches with the filter rule.
If the
- log message matches, it calls the writer and decide whether the filter set
- stops processing.
+ ezcLogFilterSet is an implementation of ezcLogMapper. ezcLogFilterSet
+ contains a set of rules, ezcLogFilterRules. These rules are
+ processed sequentially. In other words, the first assigned rule will be
+ processed first. Each rule determines whether the log message matches the
+ filter rule. If the log message matches, it calls the writer and decide
+ whether the filter set stops processing.
- The ezcLogFilterSet is inspired by modern mail applications regarding the
- mail filter settings. Normally these mail filter settings sort the incoming
- mail and stores it in the correct mail folder.
+ The ezcLogFilterSet class is inspired by modern mail application filter
+ settings. Normally these mail filter settings sort the incoming
+ mail and store it in the correct mail folder.
ezcLogWriter
- The ezcLogWriter provides an interface for the writers. An implementation
- of this interface is a valid writer, and can be addressed by the
ezcLogMapper.
- The writer itself can determine how and where the log message is stored.
+ ezcLogWriter provides an interface for the writers. An implementation
+ of this interface is a valid writer and can be addressed by ezcLogMapper.
+ The writer itself determines how and where the log message is stored.
ezcLogUnixFileWriter
- The ezcLogUnixFileWriter writes the log message to a file.
+ ezcLogUnixFileWriter writes the log message to a file.
ezcLogFilter
- The ezcLogFilter is a structure to specify which log messages are accepted in
+ ezcLogFilter is a structure to specify which log messages are accepted in
a filter set.
For more information about these classes, see the class documentation.
@@ -74,25 +73,25 @@
Examples
========
-Writing a log message to a file
+Writing a log message to file
-------------------------------
-This example creates a file writer, and assigns it to the default log mapper.
+This example creates a file writer and assigns it to the default log mapper.
.. include:: tutorial_simple_file_writer.php
:literal:
-First the tutorial_autoload.php is included. The included file loads the
-correct php files for the EventLog component.
+First, *tutorial_autoload.php* is included. This file loads the
+correct PHP files for the EventLog component.
-Hereafter the log is set up, and a message is written to the log file
-"default.log" and the file will be placed in the "/tmp/logs" directory.
+Then, the log is set up and a message is written to the log file
+*default.log*, to be placed in the */tmp/logs* directory.
-After execution, the file "/tmp/logs/default.log" contains something like::
+After execution, the file */tmp/logs/default.log* contains something like
this::
Jan 24 14:39:57 [Warning] [default] [default] Could not connect with the
payment server.
-Respectively the date, severity, source, category, and message are shown. The
+The date, severity, source, category and message are shown. The
source and category are both set to default, because they were not specified in
the message.
@@ -100,14 +99,14 @@
Assigning sources and categories
--------------------------------
-The default source and category from the ezcLog can be set via the properties
-"source" and "category". The next example demonstrates how the default
+The default source and category from ezcLog can be set via the properties
+*source* and *category*. The next example demonstrates how the default
properties can be set and how extra variables can be added to the log.
.. include:: tutorial_sources_categories.php
:literal:
-After execution, the file "/tmp/logs/default.log" contains something like::
+After execution, the file */tmp/logs/default.log* contains something like
this::
Jan 24 15:45:04 [Warning] [Payment module] [Template] Could not find cache
file: </var/cache/payment1234.cache>.
Jan 24 15:45:04 [Error] [Payment module] [SQL] Cannot execute query:
<SELECT * FROM Orders WHERE ID = '123'>.
@@ -117,7 +116,7 @@
Adding log attributes automatically
-----------------------------------
-In some cases it is convenient to add automatically log attributes to the log
+In some cases, it is convenient to automatically add log attributes to the log
message. For example:
- Audit trails should include the current user.
@@ -131,7 +130,7 @@
.. include:: tutorial_auto_variables.php
:literal:
-After execution, the file "/tmp/logs/default.log" contains::
+After execution, the file */tmp/logs/default.log* contains this::
Jan 25 10:15:19 [Failed audit] [security] [login/logoff] Authentication
failed (username: John Doe)
Jan 25 10:15:19 [Debug] [Payment] [external connections] Connecting with
the server. (service: Paynet Terminal)
@@ -141,13 +140,13 @@
Assigning log messages to different files
-----------------------------------------
-Depending on the incoming log message, the message can be stored on different
+Depending on the incoming log message, the message can be stored with different
writers. This example handles the log message as follows:
-- Ignore all message with the severity DEBUG.
-- Store the audit trails in the "audit_trails.log" file.
-- Store the logs with the Payment category in the "payment.log" file.
-- Store all the messages, except DEBUG, in the "general.log" file.
+- Ignore all messages with the severity DEBUG.
+- Store the audit trails in the *audit_trails.log* file.
+- Store the logs with the Payment category in the *payment.log* file.
+- Store all the messages, except DEBUG, in the *general.log* file.
The code is as follows:
@@ -158,14 +157,15 @@
Using trigger_error()
---------------------
-The EventLog component is designed that it can be used with trigger_error_ or
-stand-alone. Instead of calling the ezcLog::getInstance()->log() method, the
+The EventLog component is designed so that it can also be used with the
+trigger_error_ PHP method. Instead of calling the ezcLog::getInstance()->log()
method,
trigger_error() can be called. Using the trigger_error() method makes your
code
-less Log package dependent and produces less overhead when logging is disabled.
+less dependent on the EventLog component and requires less overhead when
+logging is disabled.
The function set_error_handler_ should set up a callback function (or method)
-that in its turn calls the EventLog. See for more information the
-ezcLog::logHandler() method.
+that, in turn, calls EventLog. For more information, see the API documentation
+on the ezcLog::logHandler() method.
.. _trigger_error: http://www.php.net/trigger_error
.. _set_error_handler: http://www.php.net/set_error_handler
Modified: trunk/EventLog/docs/tutorial_auto_variables.php
===================================================================
--- trunk/EventLog/docs/tutorial_auto_variables.php 2007-01-25 15:55:22 UTC
(rev 4582)
+++ trunk/EventLog/docs/tutorial_auto_variables.php 2007-01-25 20:33:13 UTC
(rev 4583)
@@ -27,7 +27,7 @@
$log->source = "Payment";
$log->log( "Connecting with the server.", ezcLog::DEBUG, array( "category" =>
"external connections" ) );
-$log->log( "Payed with creditcard.", ezcLog::SUCCESS_AUDIT, array( "category"
=> "shop" ) );
+$log->log( "Paid with credit card.", ezcLog::SUCCESS_AUDIT, array( "category"
=> "shop" ) );
?>
Modified: trunk/EventLog/docs/tutorial_multiple_log_files.php
===================================================================
--- trunk/EventLog/docs/tutorial_multiple_log_files.php 2007-01-25 15:55:22 UTC
(rev 4582)
+++ trunk/EventLog/docs/tutorial_multiple_log_files.php 2007-01-25 20:33:13 UTC
(rev 4583)
@@ -31,7 +31,7 @@
$log->source = "Payment";
$log->log( "Connecting with the server.", ezcLog::DEBUG, array( "category" =>
"external connections" ) );
-$log->log( "Payed with creditcard.", ezcLog::SUCCESS_AUDIT, array( "category"
=> "shop" ) );
+$log->log( "Paid with credit card.", ezcLog::SUCCESS_AUDIT, array( "category"
=> "shop" ) );
$log->log( "The credit card information is removed.", ezcLog::NOTICE, array(
"category" => "shop" ) );
?>
--
svn-components mailing list
svn-components@lists.ez.no
http://lists.ez.no/mailman/listinfo/svn-components
