From 0ad8bfb028d7916f7940bb48f0df616d164f74de Mon Sep 17 00:00:00 2001 From: Shyam Date: Fri, 22 May 2015 14:40:50 -0400 Subject: 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 Reviewed-on: http://review.gluster.org/10896 Tested-by: NetBSD Build System Reviewed-by: Kaleb KEITHLEY Reviewed-by: Anusha B.Rao Tested-by: Anusha B.Rao Tested-by: Gluster Build System --- doc/developer-guide/logging-guidelines.md | 132 ++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 doc/developer-guide/logging-guidelines.md (limited to 'doc/developer-guide') 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 -- cgit