reflect the change of cbps API from v0.3

[simgrid.git] / cruft / doc / tmpl / tbx_log.sgml

<!-- ##### SECTION Title ##### -->
Logging facilities

<!-- ##### SECTION Short_Description ##### -->
An easy-to-use, fast and flexible message logging architecture.

<!-- ##### SECTION Long_Description ##### -->
<para> 
  This is an adaptation of the log4c project, which is dead upstream, and which
  I was given the permission to fork under the LGPL licence by the authors. log4c
  itself was loosely based on the Apache project's Log4J, Log4CC,
  etc. project. Because C is not object oriented, a lot had to change.
</para>

<refsect2>
  <title>Overview</title>

  <para>
    There is 3 main concepts: category, priority and appender. These three
    concepts work together to enable developers to log messages according to
    message type and priority, and to control at runtime how these messages are
    formatted and where they are reported.
  </para>
</refsect2>

<refsect2>
 <title>Category hierarchy</title>

  <para>
    The first and foremost advantage of any logging API over plain printf()
    resides in its ability to disable certain log statements while allowing
    others to print unhindered. This capability assumes that the logging space,
    that is, the space of all possible logging statements, is categorized
    according to some developer-chosen criteria.
  </para>

  <para>
    This observation led to choosing category as the central concept of the
    system. Every category is declared by providing a name and an optional
    parent. If no parent is explicitly named, the root category, LOG_ROOT_CAT
    is the category's parent.
  </para>

  <para>
    A category is created by a macro call at the top level of a file.  A
    category can be created with any one of the following macros:
  </para>

  <itemizedlist>
    <listitem>
     <para>@GRAS_LOG_NEW_CATEGORY(MyCat);</para>
     <para>create a new root</para>
    </listitem>

    <listitem>
      <para>@GRAS_LOG_NEW_SUBCATEGORY(MyCat, ParentCat);</para>
      <para>Create a new category being child of the category ParentCat</para>
    </listitem>

    <listitem>
      <para>@GRAS_LOG_NEW_DEFAULT_CATEGORY(MyCat);</para>
      <para>Like GRAS_LOG_NEW_CATEGORY, but the new category is the default one
      in this file</para>
    </listitem>

    <listitem>
      <para>@GRAS_LOG_NEW_DEFAULT_SUBCATEGORY(MyCat, ParentCat);</para>
      <para>Like GRAS_LOG_NEW_SUBCATEGORY, but the new category is the default one
      in this file</para>
    </listitem>
  </itemizedlist>

  <para>
    The parent cat can be defined in the same file or in another file, but each
    category may have only one definition.
  </para>

  <para>
    Typically, there will be a Category for each module and sub-module, so you
    can independently control logging for each module.
  </para>
</refsect2>

<refsect2>
  <title>Priority</title>

  <para>
    A category may be assigned a threshold priorty. The set of priorites are
    defined by the @gras_log_priority_t enum. Their values are DEBUG, VERBOSE,
    INFO, WARNING, ERROR and CRITICAL.
  </para>

  <para>
    If a given category is not assigned a threshold priority, then it inherits
    one from its closest ancestor with an assigned threshold.
  </para>
 
  <para>
    To ensure that all categories can eventually inherit a threshold, the root
    category always has an assigned threshold priority.
  </para>

  <para>
    Logging requests are made by invoking a logging macro on a category.  All
    of the macros have a printf-style format string followed by arguments.
    Because most C compilers do not support vararg macros, there is a version
    of the macro for any number of arguments from 0 to 6. The macro name ends
    with the total number of arguments.
  </para>

  <para>
    Here is an example of the most basic type of macro:
  </para>
  
  <programlisting>CLOG5(MyCat, gras_log_priority_warning, "Values are: %d and '%s'", 5, "oops");</programlisting>
  
  <para>This is a logging request with priority WARN.</para>

  <para>
    A logging request is said to be enabled if its priority is higher than or
    equal to the threshold priority of its category. Otherwise, the request is
    said to be disabled. A category without an assigned priority will inherit
    one from the hierarchy.
  </para>

  <para>
    It is possible to use any non-negative integer as a priority. If, as in the
    example, one of the standard priorites is used, then there is a convenience
    macro that is typically used instead. For example, the above example is
    equivalent to the shorter:
  </para>

  <programlisting>CWARN4(MyCat, "Values are: %d and '%s'", 5, "oops");</programlisting>
</refsect2>

<refsect2>
  <title>Default category</title>

  <para>
    If @GRAS_LOG_NEW_DEFAULT_SUBCATEGORY(MyCat, Parent) or
    @GRAS_LOG_NEW_DEFAULT_CATEGORY(MyCat) is used to create the category, then
    the even shorter form can be used:
  </para>

  <programlisting>WARN3("Values are: %d and '%s'", 5, "oops");</programlisting>

  <para>
   Only one default category can be created per file, though multiple
   non-defaults can be created and used.
  </para>
</refsect2>

<refsect2>
  <title>Example</title>

  <para>Here is a more complete example:</para>

  <programlisting>
     #include "gras.h"

     /* create a category and a default subcategory */
     GRAS_LOG_NEW_CATEGORY(VSS);
     GRAS_LOG_NEW_DEFAULT_SUBCATEGORY(SA, VSS);

     main() {
            /* Now set the parent's priority.
               (the string would typcially be a runtime option) */
            gras_log_control_set("SA.thresh=3");

            /* This request is enabled, because WARNING &gt;= INFO. */
            CWARN2(VSS, "Low fuel level.");

            /* This request is disabled, because DEBUG &lt; INFO. */
            CDEBUG2(VSS, "Starting search for nearest gas station."); 

            /* The default category SA inherits its priority from VSS. Thus,
               the following request is enabled because INFO &gt;= INFO.  */
            INFO1("Located nearest gas station.");

            /* This request is disabled, because DEBUG &lt; INFO. */
            DEBUG1("Exiting gas station search");
      }</programlisting>
</refsect2>

<refsect2>
  <title>Configuration</title>

  <para>
    Configuration is typically done during program initialization by invoking
    the gras_log_control_set() method. The control string passed to it
    typically comes from the command line. Look at the doucmentation for that
    function for the format of the control string.
  </para>
</refsect2>

<refsect2>
  <title>Performance</title>

  <para>
    Clever design insures efficiency. Except for the first invocation, a
    disabled logging request requires an a single comparison of a static
    variable to a constant.
  </para>

  <para>
    There is also compile time constant, @GRAS_LOG_STATIC_THRESHOLD, which
    causes all logging requests with a lower priority to be optimized to 0 cost
    by the compiler. By setting it to gras_log_priority_infinite, all logging
    requests are statically disabled and cost nothing. Released executables
    might typically be compiled with
    "-DGRAS_LOG_STATIC_THRESHOLD=gras_log_priority_infinite".
  </para>
</refsect2>

<refsect2>
  <title>Appenders</title>

  <para>
    Each category has an optional appender. An appender is a pointer to a
    structure whcih starts with a pointer to a doAppend() function. DoAppend()
    prints a message to a log.
  </para>

  <para>
    WHen a category is passed a message by one of the logging macros, the
    category performs the following actions:
  </para>

  <itemizedlist>
    <listitem>
       <para>
         if the category has an appender, the message is passed to the
         appender's doAppend() function,
       </para>
    </listitem>

    <listitem>
       <para>
         if 'willLogToParent' is true for the category, the message is passed
         to the category's parent.
      </para>

      <para>
         By default, all categories except root have no appender and
         'willLogToParent' is true. This situation causes all messages to be
         logged by the root category's appender.
      </para>

      <para>
         Typically, you would only change the root category's appender when you
         wanted, say, a different output format. Copying defaultLogAppender.c
         would be a good start.
      </para>

      <para>
         The default appender function currently prints to stderr, but more
         would be needed, like the one able to send the logs to a remote
         dedicated server.
      </para>
    </listitem>
  </itemizedlist>
</refsect2>

<refsect2>
  <title>Misc and Caveats</title>

  <para>
    Do not use any of the macros that start with '_'.
  </para>

  <para>
    The current set of macros force each file to use categories declared in
    that file. This is intentional. Make the category a child of the file's
    module category.
  </para>

  <para>
    Log4J has a 'rolling file appender' which you can select with a run-time
    option and specify the max file size. This would be a nice default for
    non-kernel applications.
  </para>

  <para>
    Careful, category names are global variables.
  </para>
</refsect2>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### ENUM gras_log_priority_t ##### -->
<para>

</para>

@gras_log_priority_none: 
@gras_log_priority_debug: 
@gras_log_priority_verbose: 
@gras_log_priority_info: 
@gras_log_priority_warning: 
@gras_log_priority_error: 
@gras_log_priority_critical: 
@gras_log_priority_infinite: 
@gras_log_priority_uninitialized: 

<!-- ##### FUNCTION gras_log_control_set ##### -->
<para>

</para>

@cs: 
@Returns: 


<!-- ##### MACRO GRAS_LOG_NEW_CATEGORY ##### -->
<para>

</para>

@catName: 


<!-- ##### MACRO GRAS_LOG_NEW_SUBCATEGORY ##### -->
<para>

</para>

@catName: 
@parent: 


<!-- ##### MACRO GRAS_LOG_NEW_DEFAULT_CATEGORY ##### -->
<para>

</para>

@cname: 


<!-- ##### MACRO GRAS_LOG_NEW_DEFAULT_SUBCATEGORY ##### -->
<para>

</para>

@cname: 
@parent: 


<!-- ##### MACRO GRAS_LOG_DEFAULT_CATEGORY ##### -->
<para>

</para>

@cname: 


<!-- ##### MACRO GRAS_LOG_EXTERNAL_CATEGORY ##### -->
<para>

</para>

@cname: 


<!-- ##### MACRO GRAS_LOG_ISENABLED ##### -->
<para>

</para>

@catName: 
@priority: 


<!-- ##### MACRO GRAS_LOG_STATIC_THRESHOLD ##### -->
<para>

</para>



<!-- ##### FUNCTION gras_log_appender_set ##### -->
<para>

</para>

@cat: 
@app: 


<!-- ##### VARIABLE gras_log_default_appender ##### -->
<para>

</para>


<!-- ##### MACRO CDEBUG6 ##### -->
<para>

</para>

@c: 
@f: 
@a1: 
@a2: 
@a3: 
@a4: 
@a5: 
@a6: 


<!-- ##### MACRO CVERB6 ##### -->
<para>

</para>

@c: 
@f: 
@a1: 
@a2: 
@a3: 
@a4: 
@a5: 
@a6: 


<!-- ##### MACRO CINFO6 ##### -->
<para>

</para>

@c: 
@f: 
@a1: 
@a2: 
@a3: 
@a4: 
@a5: 
@a6: 


<!-- ##### MACRO CWARN6 ##### -->
<para>

</para>

@c: 
@f: 
@a1: 
@a2: 
@a3: 
@a4: 
@a5: 
@a6: 


<!-- ##### MACRO CERROR6 ##### -->
<para>

</para>

@c: 
@f: 
@a1: 
@a2: 
@a3: 
@a4: 
@a5: 
@a6: 


<!-- ##### MACRO CCRITICAL6 ##### -->
<para>

</para>

@c: 
@f: 
@a1: 
@a2: 
@a3: 
@a4: 
@a5: 
@a6: 


<!-- ##### MACRO DEBUG6 ##### -->
<para>

</para>

@f: 
@a1: 
@a2: 
@a3: 
@a4: 
@a5: 
@a6: 


<!-- ##### MACRO VERB6 ##### -->
<para>

</para>

@f: 
@a1: 
@a2: 
@a3: 
@a4: 
@a5: 
@a6: 


<!-- ##### MACRO INFO6 ##### -->
<para>

</para>

@f: 
@a1: 
@a2: 
@a3: 
@a4: 
@a5: 
@a6: 


<!-- ##### MACRO WARN6 ##### -->
<para>

</para>

@f: 
@a1: 
@a2: 
@a3: 
@a4: 
@a5: 
@a6: 


<!-- ##### MACRO ERROR6 ##### -->
<para>

</para>

@f: 
@a1: 
@a2: 
@a3: 
@a4: 
@a5: 
@a6: 


<!-- ##### MACRO CRITICAL6 ##### -->
<para>

</para>

@f: 
@a1: 
@a2: 
@a3: 
@a4: 
@a5: 
@a6: