doc: Add documentation for new logging framework

This commit adds a guideline document for using the new message
logging infrastructure.

Change-Id: Iddc6a2b6f244cc5b51dab4c99d963e89b1a9f478
Signed-off-by: Shyam <srangana@redhat.com>
Reviewed-on: http://review.gluster.org/10896
Tested-by: NetBSD Build System <jenkins@build.gluster.org>
Reviewed-by: Kaleb KEITHLEY <kkeithle@redhat.com>
Reviewed-by: Anusha B.Rao <anusha91rao@gmail.com>
Tested-by: Anusha B.Rao <anusha91rao@gmail.com>
Tested-by: Gluster Build System <jenkins@build.gluster.com>

1 files changed, 132 insertions, 0 deletions

diff --git a/doc/developer-guide/logging-guidelines.md b/doc/developer-guide/logging-guidelines.md
new file mode 100644
index 00000000000..58adf944b67
--- /dev/null
+++ b/doc/developer-guide/logging-guidelines.md
@@ -0,0 +1,132 @@
+Guidelines on using the logging framework within a component
+============================================================
+Gluster library libglusterfs.so provides message logging abstractions that
+are intended to be used across all code/components within gluster.
+
+There could be potentially 2 major cases how the logging infrastructure is
+used,
+  - A new gluster service daemon or end point is created
+    - The service daemon infrastructure itself initlializes the logging
+    infrastructure (i.e calling gf_log_init and related set functions)
+      - See, glusterfsd.c:logging_init
+    - Alternatively there could be a case where an end point service (say
+    gfapi) may need to do the required initialization
+    - This document does not (yet?) cover guidelines for these cases. Best
+    bet would be to look at code in glusterfsd.c:logging_init (or equivalent)
+    in case a need arises and you reach this document.
+  - A new xlator or subcomponent is written as a part of the stack
+    - Primarily in this case, the consumer of the logging APIs would only
+    invoke an API to *log* a particular message at a certain severity
+    - This document elaborates on this use of the message logging framework
+    in this context
+
+There are 2 interfaces provided to log messages,
+1. The older gf_log* interface
+2. The newer gf_msg* interface
+
+1. Older _to_be_deprecated_ gf_log* interface
+  - Not much documentation is provided for this interface here, as these are
+  meant to be deprecated and all code should be moved to the newer gf_msg*
+  interface
+
+2. New gf_msg* interface
+  - The set of interfaces provided by gf_msg are,
+    - NOTE: It is best to consult logging.h for the latest interfaces, as
+    this document may get out of sync with the code
+
+    *gf_msg(dom, levl, errnum, msgid, fmt...)*
+      - Used predominantly to log a message above TRACE and DEBUG levels
+      - See further guidelines below
+
+    *gf_msg_debug(dom, errnum, fmt...)*
+    *gf_msg_trace(dom, errnum, fmt...)*
+      - Above are handy shortcuts for TRACE and DEBUG level messages
+      - See further guidelines below
+
+    *gf_msg_callingfn(dom, levl, errnum, msgid, fmt...)*
+      - Useful function when a backtrace to detect calling routines that
+      reached this execution point needs to be logged in addition to the
+      message
+      - This is very handy for framework libraries or code, as there could
+      be many callers to the same, and the real failure would need the call
+      stack to determine who the caller actually was
+      - A good example is the dict interfaces using this function to log who
+      called, when a particular error/warning needs to be displayed
+      - See further guidelines below
+
+    *gf_msg_plain(levl, fmt...)*
+    *gf_msg_plain_nomem(levl, msg)*
+    *gf_msg_vplain(levl, fmt, va)*
+    *gf_msg_backtrace_nomem*
+      - The above interfaces are provided to log messages without any typical
+      headers (like the time stamp, dom, errnum etc.). The primary users of
+      the above interfaces are, when printing the final graph, or printing
+      the configuration when a process is about dump core or abort, or
+      printing the backtrace when a process recieves a critical signal
+      - These interfaces should not be used outside the scope of the users
+      above, unless you know what you are doing
+
+    *gf_msg_nomem(dom, levl, size)*
+      - Very crisp messages, throwing out file, function, line numbers, in
+      addition to the passed in size
+      - These are used in the memory allocation abstractions interfaces in
+      gluster, when the allocation fails (hence a no-mem log message, so that
+      further allocation is not attempted by the logging infrastructure)
+      - If you are contemplating using these, then you know why and how
+
+  - Guidelines for the various arguments to the interfaces
+    **dom**
+      - The domain from which this message appears, IOW for xlators it should
+      be the name of the xlator (as in this->name)
+
+      - The intention of this string is to distinguish from which
+      component/xlator the message is being printed
+
+      - This information can also be gleaned from the FILE:LINE:FUNCTION
+      information printed in the message anyway, but is retained to provide
+      backward compatability to the messages as seen by admins earlier
+
+    **levl**
+      - Consult logging.h:gf_loglevel_t for logging levels (they pretty much
+      map to syslog levels)
+
+    **errnum**
+      - errno should be passed in here, if available, 0 otherwise. This auto
+      enables the logging infrastructure to print (man 3) strerror form of the
+      same at the end of the message in a consistent format
+
+      - If any message is already adding the strerror as a parameter to the
+      message, it is suggested/encouraged to remove the same and pass it as
+      errnum
+
+      - The intention is that, if all messages did this using errnum and not
+      as a part of their own argument list, the output would look consistent
+      for the admin and cross component developers when reading logs
+
+    **msgid**
+      - This is a unique message ID per message (which now is more a message
+      ID per group of messages in the implementation)
+
+      - Rules for generating this ID can be found in dht-messages.h (it used
+      to be template-common-messages.h, but that template is not updated,
+      this comment should be changed once that is done) and glfs-message-id.h
+
+      - Every message that is *above* TRACE and DEBUG should get a message
+      ID, as this helps generating message catalogs that can help admins to
+      understand the context of messages better. Another intention is that
+      automated message parsers could detect a class of message IDs and send
+      out notifications on the same, rather than parse the message string
+      itself (which if it changes, the input to the parser has to change, etc.
+      and hence is better to retain message IDs)
+
+      - Ok so if intention is not yet clear, look at journald MESSAGE ID
+      motivation, as that coupled with ident/dom above is expected to provide
+      us with similar advantages
+
+      - Bottomline: Every message gets its own ID, in case a message is
+      *not* DEBUG or TRACE and still is developer centric, a generic message
+      ID per component *maybe* assigned to the same to provide ease of use
+      of the API
+
+    **fmt**
+      - As in format argument of (man 3) printf