summaryrefslogtreecommitdiffstats
path: root/doc/developer-guide
diff options
context:
space:
mode:
authorShyam <srangana@redhat.com>2015-05-22 14:40:50 -0400
committerKaleb KEITHLEY <kkeithle@redhat.com>2015-07-17 07:20:46 -0700
commit0ad8bfb028d7916f7940bb48f0df616d164f74de (patch)
tree6c09b5f6b4482b6e2dca148e8478600c94018c45 /doc/developer-guide
parentb21f3b3ce69c6b1b0eb6f8243b5c601c5c4b7cbe (diff)
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>
Diffstat (limited to 'doc/developer-guide')
-rw-r--r--doc/developer-guide/logging-guidelines.md132
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