[myserver-commit] [2846] Added a first document scratch about the new log management usage.

[Francesco Pipita]

Revision: 2846
          http://svn.sv.gnu.org/viewvc/?view=rev&root=myserver&revision=2846
Author:   francesco_pipita
Date:     2008-09-27 14:22:55 +0000 (Sat, 27 Sep 2008)

Log Message:
-----------
Added a first document scratch about the new log management usage.

Modified Paths:
--------------
    trunk/myserver/documentation/myserver.texi

Added Paths:
-----------
    trunk/myserver/documentation/log_management.texi

Added: trunk/myserver/documentation/log_management.texi
===================================================================
--- trunk/myserver/documentation/log_management.texi                            
(rev 0)
+++ trunk/myserver/documentation/log_management.texi    2008-09-27 14:22:55 UTC 
(rev 2846)
@@ -0,0 +1,115 @@
address@hidden -*-texinfo-*-
+
address@hidden Overview of the log management features
+The MyServer's log management system was designed to support logging
+over different targets. By default, log messages can be sent to a file,
+to a socket and of course to the console. The main class which achieves
+logging tasks is still the @code{LogManager} class. One single instance
+of it can now handle multiple targets. These targets are called
address@hidden objects. In addition, it is possible to provide a list
+of filters (e.g. the Gzip filter) to each @code{LogStream} object. This
+offers interesting possibilities, like logging over a TCP Socket while
+taking advantage of the Gzip compression. The new @code{LogManager} also
+ensures that all the operations that modify its internal data
+structures, through its interface, are atomics.
+
address@hidden Use of the new LogManager interface
+This section introduces the use of the new @code{LogManager}'s
+interface.
+
address@hidden Construction
+The @code{LogManager} constructor, requires an instance of
address@hidden, an instance of @code{LogStreamFactory} and a
+logging level, choosen between @code{INFO, WARNING, ERROR}. The third
+parameter is optional. 
address@hidden
+LogManager (FiltersFactory* filtersFactory,
+            LogStreamFactory* logStreamFactory,
+            LoggingLevel level = WARNING);
address@hidden example
+
+
address@hidden Adding a new LogStream target
+The adding of a new @code{LogStream} target can be done calling the
address@hidden method over an instance of the
address@hidden Below, we can look at the method signature :
address@hidden
+int addLogStream (string location, 
+                  list<string>& filters, 
+                  u_long cycleLog);
address@hidden example
+The @code{location} string holds the location where the @code{LogStream}
+will point to as well as the protocol it will use. That string must
+follow a special syntax, that will be covered in next section. The
address@hidden parameter holds a list of filter names that will be added
+to the @code{LogStream}. Finally, the @code{cycleLog} parameter holds
+the max size, in bytes, that the new @code{LogStream} can reach. Over
+that limit, the @code{LogStream} will be cycled, that is, its content
+will be saved somewhere else. The current @code{LogStream} will be
+emptied and the location name of its saved content, will be available
+looking at the latest element of a FIFO queue returned by the
address@hidden method. The @code{addLogStream} method returns a
+zero value if the new @code{LogStream} was successful added, a non-zero
+value otherwise, according to the MyServer standard.
+
address@hidden Location strings
+A location string must be provided in the form
address@hidden://path/to/resource}'. The address@hidden://}' part is
+used by the @code{LogStreamFactory} to fetch the proper constructor for
+the new object that it will create. The address@hidden/to/resource}' part,
+instead, is used within the @code{LogStreamCreator}. The
address@hidden creation process, must ensure, through checks at
+increasing depth levels, that only valid @code{LogStream} objects can
+be returned. For example, syntactically a location string like
address@hidden://foo_host:-1}' is correct, but of course, the
address@hidden/to/resource}' part doesn't represent any valid host:port 
+pair for a socket. So giving a such location string, the
address@hidden method, must fail.
+
address@hidden Removing an existing LogStream
+The interface provides also a method that can detach a @code{LogStream}
+from the @code{LogManager}. Here is the method signature :
address@hidden
+int removeLogStream (string location);
address@hidden example
+It will remove the @code{LogStream} that points to @code{location}. If
+the provided location doesn't belong to the @code{LogManager}, the
+method doesn't nothing and it simply returns a non-zero value.
+
address@hidden Adding new LogStream classes
+To add new targets which can be used within the @code{LogManager}, you
+have to subclass the @code{LogStream} class. Then, if needed, override
+the following virtual methods :
address@hidden
+virtual u_long streamSize ();
+virtual int streamCycle ();
address@hidden example
+The first one should return the size of the @code{Stream} owned by the
address@hidden while the second should manage its cycling process. The
+return value for the latter method must conform with the MyServer
+standard. The next step is to subclass @code{LogStreamCreator},
+overriding the @code{create} abstract method. Finally, you have to add
+the new @code{LogStreamCreator} to the @code{LogStreamFactory}, merely
+adding a line to its constructor, something that looks like :
address@hidden
+logStreamCreators["foo://"] = new FooStreamCreator ();
address@hidden example
+
address@hidden Writing log messages on the LogStream objects
+To log messages, simply call the method @code{log} on a
address@hidden object. That method takes three parameters, but only
+the first one is needed.
address@hidden
+int log (string message, 
+         LoggingLevel level = WARNING, 
+         string location = "all");
address@hidden example
+The first parameter represent a message to output on the log. The
address@hidden parameter represent the @code{LoggingLevel} of the incoming
+message. If it is lesser than the @code{LogManager}'s logging level, the
address@hidden discards the message. The @code{location} parameter
+tells the @code{LogManager} to output the message only to the specified
+location. By default, if no @code{location} is provided, the
address@hidden will log the message on all its
address@hidden objects. If a non-valid or non-existent location is
+provided, the @code{LogManager} simply discards the message.


Property changes on: trunk/myserver/documentation/log_management.texi
___________________________________________________________________
Name: svn:mergeinfo
   + 

Modified: trunk/myserver/documentation/myserver.texi
===================================================================
--- trunk/myserver/documentation/myserver.texi  2008-09-27 11:35:47 UTC (rev 
2845)
+++ trunk/myserver/documentation/myserver.texi  2008-09-27 14:22:55 UTC (rev 
2846)
@@ -72,6 +72,7 @@
 * MIME types:: MIME types configuration.
 * Process security:: Process security.
 * SSL certificates:: Show how to use SSL certificates.
+* Log management:: Describe how to use the log management features.
 
 * Concept Index::       An item for each concept.
 @end menu
@@ -104,12 +105,17 @@
 @cindex Process security
 @include process_security.texi
 
address@hidden SSL certificates, Concept Index, Process security, Top
address@hidden SSL certificates, Log management, Process security, Top
 @chapter SSL certificates
 @cindex SSL certificates
 @include ssl_certificates.texi
 
address@hidden Concept Index, , SSL certificates, Top
address@hidden Log management, Concept Index, SSL certificates, Top
address@hidden Log management
address@hidden Log Management
address@hidden log_management.texi
+
address@hidden Concept Index, , Log management, Top
 @unnumbered Concept Index
 @printindex cp