Author: Raymond Bosman Date: 2006-01-25 16:02:23 +0100 (Wed, 25 Jan 2006) New Revision: 2029
Log: - Added the tutorial. Added: packages/EventLog/trunk/docs/tutorial.txt packages/EventLog/trunk/docs/tutorial_auto_variables.php packages/EventLog/trunk/docs/tutorial_autoload.php packages/EventLog/trunk/docs/tutorial_database.php packages/EventLog/trunk/docs/tutorial_multiple_log_files.php packages/EventLog/trunk/docs/tutorial_simple_file_writer.php packages/EventLog/trunk/docs/tutorial_sources_categories.php Added: packages/EventLog/trunk/docs/tutorial.txt =================================================================== --- packages/EventLog/trunk/docs/tutorial.txt 2006-01-25 14:52:48 UTC (rev 2028) +++ packages/EventLog/trunk/docs/tutorial.txt 2006-01-25 15:02:23 UTC (rev 2029) @@ -0,0 +1,207 @@ +eZ components - EventLog +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. contents:: Table of Contents + +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 available log writers are: + +- ezcLogWriterDatabase, which writes log messages to the database. +- ezcLogWriterUnixFile, which writes log messages to a file in an 'Unix' file + format. + +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 variables from the log message and sends the log +message only to the writers that match with the log variables. + + +Class overview +============== + +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 + 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. + +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. + +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 can executes the writer and decide whether it 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. + +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. + +ezcLogWriterUnixFile + The ezcLogWriterUnixFile writes the log message to a file. + +ezcLogWriterDatabase + The ezcLogWriterDatabase writes the log message to a database. + +ezcLogFilter + The 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. + + +Installation +============ + +This tutorial assumes that you have set-up an eZ components environment. For +information on how to do this, please refer to the ComponentsIntroduction_. + +.. _ComponentsIntroduction: http://ez.no/community/articles/an_introduction_to_ez_components + + +Examples +======== + + +Writing a log message to a file. +-------------------------------- + +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. Hereafter the time zone is set to +"UTC". The log uses some date functions and without a time zone set, PHP may +show warnings. + +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/log" directory. + +After execution, the file "/tmp/log/default.php" contains something like:: + + 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 +source and category are both set to default, because they were not specified in +the message. + + +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 +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/log/default.php" contains something like:: + + 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'>. + Jan 24 15:45:04 [Debug] [Payment module] Starting shutdown process. (file: /home/rb/php5/ezcomponents/packages/EventLog/trunk/docs/tutorial_sources_categories.php, line: 25) + + +Adding log attributes automatically +----------------------------------- + +Some cases it is convenient to add automatically log attributes to the log +message. For example: + +- Audit trails should include the current user. +- A payment system should always include the order number. + +However, the log attributes appended to the log message are static. The +value assigned to the attribute will be the same. + +The next example assigns two automatic attributes: + +.. include:: tutorial_auto_variables.php + :literal: + +After execution, the file "/tmp/log/default.php" contains:: + + 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) + Jan 25 10:15:19 [Success audit] [Payment] [shop] Payed with creditcard. (username: John Doe, service: Paynet Terminal) + + +Assigning log messages to different files +----------------------------------------- + +Depending on the incoming log message, the message can be stored on different +writers. This example handles the log message as follow: + +- Ignore all message with the severity DEBUG. +- Store the audit trails in the "audit.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: + +.. include:: tutorial_multiple_log_files.php + :literal: + + + +Writing to the MySQL database +----------------------------- + +To write log messages to the database, the Database component is used. The +table to which the log is written should already exist. + +.. include:: tutorial_database.php + :literal: + +The database: "logs" and the table "general" should exist. The table should at +least contain the columns: time, message, severity, source, category. An +example MySQL query to create the table:: + + CREATE TABLE `general` + ( + `id` INT NOT NULL AUTO_INCREMENT, + `time` DATETIME NOT NULL, + `message` VARCHAR( 255 ) NOT NULL, + `severity` VARCHAR( 40 ) NOT NULL, + `source` VARCHAR( 100 ) NOT NULL , + `category` VARCHAR( 100 ) NOT NULL, + `file` VARCHAR( 100 ) NOT NULL, + `line` INT NOT NULL, + PRIMARY KEY ( `id` ) + ) + + + +.. + Local Variables: + mode: rst + fill-column: 79 + End: + vim: et syn=rst tw=79 Property changes on: packages/EventLog/trunk/docs/tutorial.txt ___________________________________________________________________ Name: svn:eol-style + native Added: packages/EventLog/trunk/docs/tutorial_auto_variables.php =================================================================== --- packages/EventLog/trunk/docs/tutorial_auto_variables.php 2006-01-25 14:52:48 UTC (rev 2028) +++ packages/EventLog/trunk/docs/tutorial_auto_variables.php 2006-01-25 15:02:23 UTC (rev 2029) @@ -0,0 +1,33 @@ +<?php + +include( "tutorial_autoload.php" ); +date_default_timezone_set( "UTC" ); + +// Same set up as the previous examples. +$log = ezcLog::getInstance(); +$writer = new ezcLogWriterUnixFile( "/tmp/logs", "default.log" ); +$log->getmapper()->appendRule( new ezcLogFilterRule( new ezcLogFilter, $writer, true ) ); + +// ... + +$username = "John Doe"; +$service = "Paynet Terminal"; + +// ... + +// Add automatically the username to the log message, when the log message is either a SUCCESS_AUDIT or a FAILED_AUDIT. +$log->setSeverityAttributes( ezcLog::SUCCESS_AUDIT | ezcLog::FAILED_AUDIT, array( "username" => $username ) ); + +// Same can be done with the source of the log message. +$log->setSourceAttributes( array( "Payment" ), array( "service" => $service ) ); + +// Writing some log messages. +$log->log( "Authentication failed", ezcLog::FAILED_AUDIT, array( "source" => "security", "category" => "login/logoff" ) ); + +$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" ) ); + + +?> Property changes on: packages/EventLog/trunk/docs/tutorial_auto_variables.php ___________________________________________________________________ Name: svn:eol-style + native Added: packages/EventLog/trunk/docs/tutorial_autoload.php =================================================================== --- packages/EventLog/trunk/docs/tutorial_autoload.php 2006-01-25 14:52:48 UTC (rev 2028) +++ packages/EventLog/trunk/docs/tutorial_autoload.php 2006-01-25 15:02:23 UTC (rev 2029) @@ -0,0 +1,23 @@ +<?php + +require_once 'Base/trunk/src/base.php'; + +/** + * Autoload ezc classes + * + * @param string $class_name + */ +function __autoload( $class_name ) +{ + if ( ezcBase::autoload( $class_name ) ) + { + return; + } + if ( strpos( $class_name, '_' ) !== false ) + { + $file = str_replace( '_', '/', $class_name ) . '.php'; + require_once( $file ); + } +} + +?> Property changes on: packages/EventLog/trunk/docs/tutorial_autoload.php ___________________________________________________________________ Name: svn:eol-style + native Added: packages/EventLog/trunk/docs/tutorial_database.php =================================================================== --- packages/EventLog/trunk/docs/tutorial_database.php 2006-01-25 14:52:48 UTC (rev 2028) +++ packages/EventLog/trunk/docs/tutorial_database.php 2006-01-25 15:02:23 UTC (rev 2029) @@ -0,0 +1,21 @@ +<?php + +include( "tutorial_autoload.php" ); +date_default_timezone_set( "UTC" ); + +// Open database connection. +$db = ezcDbFactory::create( "mysql://[EMAIL PROTECTED]/logs" ); + +// Create the database writer. +// Attach to the database handler. And write log entries to the table: "default". +$writer = new ezcLogWriterDatabase( $db, "general"); + +$log = ezcLog::getInstance(); + +// Write everything to the database. +$log->getmapper()->appendRule( new ezcLogFilterRule( new ezcLogFilter, $writer, true ) ); + +// Write a message +$log->log( "Cannot load Payment module", ezcLog::ERROR, array( "source" => "shop", "category" => "modules" ) ); + +?> Property changes on: packages/EventLog/trunk/docs/tutorial_database.php ___________________________________________________________________ Name: svn:eol-style + native Added: packages/EventLog/trunk/docs/tutorial_multiple_log_files.php =================================================================== --- packages/EventLog/trunk/docs/tutorial_multiple_log_files.php 2006-01-25 14:52:48 UTC (rev 2028) +++ packages/EventLog/trunk/docs/tutorial_multiple_log_files.php 2006-01-25 15:02:23 UTC (rev 2029) @@ -0,0 +1,37 @@ +<?php +include( "tutorial_autoload.php" ); +date_default_timezone_set( "UTC" ); + +// Same set up as the previous examples. +$log = ezcLog::getInstance(); + +// Create the writers +$writeAll = new ezcLogWriterUnixFile( "/tmp/logs", "general.log" ); +$writePayment = new ezcLogWriterUnixFile( "/tmp/logs", "payment.log" ); +$writeAuditTrails = new ezcLogWriterUnixFile( "/tmp/logs", "audit_trails.log" ); + +$debugFilter = new ezcLogFilter; +$debugFilter->severity = ezcLog::DEBUG; +$log->getmapper()->appendRule( new ezcLogFilterRule( $debugFilter, array(), false ) ); + +$auditFilter = new ezcLogFilter; +$auditFilter->severity = ezcLog::SUCCESS_AUDIT | ezcLog::FAILED_AUDIT; +$log->getMapper()->appendRule( new ezcLogFilterRule( $auditFilter, $writeAuditTrails, true ) ); + +$paymentFilter = new ezcLogFilter; +$paymentFilter->source = array( "Payment" ); +$log->getMapper()->appendRule( new ezcLogFilterRule( $paymentFilter, $writePayment, true ) ); + +$log->getMapper()->appendRule( new ezcLogFilterRule( new ezcLogFilter, $writeAll, true ) ); + + +// Writing some log messages. +$log->log( "Authentication failed", ezcLog::FAILED_AUDIT, array( "source" => "security", "category" => "login/logoff" ) ); + +$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( "The credit card information is removed.", ezcLog::NOTICE, array( "category" => "shop" ) ); +?> Property changes on: packages/EventLog/trunk/docs/tutorial_multiple_log_files.php ___________________________________________________________________ Name: svn:eol-style + native Added: packages/EventLog/trunk/docs/tutorial_simple_file_writer.php =================================================================== --- packages/EventLog/trunk/docs/tutorial_simple_file_writer.php 2006-01-25 14:52:48 UTC (rev 2028) +++ packages/EventLog/trunk/docs/tutorial_simple_file_writer.php 2006-01-25 15:02:23 UTC (rev 2029) @@ -0,0 +1,27 @@ +<?php + +include( "tutorial_autoload.php" ); +date_default_timezone_set( "UTC" ); + +// Get the one and only instance of the ezcLog. +$log = ezcLog::getInstance(); + +// Get an instance to the default log mapper. +$mapper = $log->getMapper(); + +// Create a new Unix file writer, that writes to the file: "default.log". +$writer = new ezcLogWriterUnixFile( "/tmp/logs", "default.log" ); + +// Create a filter that accepts every message (default behavior). +$filter = new ezcLogFilter; + +// Combine the filter with the writer in a filter rule. +$rule = new ezcLogFilterRule( $filter, $writer, true ); + +// And finally assign the rule to the mapper. +$mapper->appendRule( $rule ); + +// Write a message to the log. +$log->log( "Could not connect with the payment server.", ezcLog::WARNING ); + +?> Property changes on: packages/EventLog/trunk/docs/tutorial_simple_file_writer.php ___________________________________________________________________ Name: svn:eol-style + native Added: packages/EventLog/trunk/docs/tutorial_sources_categories.php =================================================================== --- packages/EventLog/trunk/docs/tutorial_sources_categories.php 2006-01-25 14:52:48 UTC (rev 2028) +++ packages/EventLog/trunk/docs/tutorial_sources_categories.php 2006-01-25 15:02:23 UTC (rev 2029) @@ -0,0 +1,28 @@ +<?php + +include( "tutorial_autoload.php" ); +date_default_timezone_set( "UTC" ); + +// Same set up as the previous example. +$log = ezcLog::getInstance(); +$writer = new ezcLogWriterUnixFile( "/tmp/logs", "default.log" ); +$log->getmapper()->appendRule( new ezcLogFilterRule( new ezcLogFilter, $writer, true ) ); + +// Set the source and category. +$log->source = "Payment module"; +$log->category = "Template"; + +$log->log( "Could not find cache file: </var/cache/payment1234.cache>.", ezcLog::WARNING ); + +// ... + +// Write a SQL error. The category is set to SQL for this message only. +$log->log( "Cannot execute query: <SELECT * FROM Orders WHERE ID = '123'>.", ezcLog::ERROR, array( "category" => "SQL" ) ); + +// ... + +// Write a debug message that includes the current filename and line number. +// The category is left out. +$log->log( "Starting shutdown process.", ezcLog::DEBUG, array( "category" => "", "file" => __FILE__, "line" => __LINE__ ) ); + +?> Property changes on: packages/EventLog/trunk/docs/tutorial_sources_categories.php ___________________________________________________________________ Name: svn:eol-style + native -- svn-components mailing list [email protected] http://lists.ez.no/mailman/listinfo/svn-components
