Saturday, October 30, 2010

Choosing severity levels

A recent enquiry on the Pantheios Help Forum requested guidance for what severity levels to use in what circumstances. Although I've a strong opinion on this, which I'll include in a series of articles on diagnostic logging that I'm currently preparing for Dr. Dobbs (and which I hope will see publication over Dec-Feb), I'm happy to volunteer the basic ideas here.

Although Pantheios can be used with any range severity levels that fits into the int type - which usually means 32- or 64-bits, depending on platform - as it ships Pantheios defines eight stock severity levels, corresponding to the eight levels defined by SysLog, as follows:


Syslog levelPantheios level (C)Pantheios level (C++)Integer value
EmergencyPANTHEIOS_SEV_EMERGENCYpantheios::emergency0
AlertPANTHEIOS_SEV_ALERTpantheios::ealert1
CriticalPANTHEIOS_SEV_CRITICALpantheios::critical2
ErrorPANTHEIOS_SEV_ERRORpantheios::error3
WarningPANTHEIOS_SEV_WARNINGpantheios::warning4
NoticePANTHEIOS_SEV_NOTICEpantheios::notice5
InfoPANTHEIOS_SEV_INFOpantheios::info6
DebugPANTHEIOS_SEV_DEBUGpantheios::debug7

Briefly, we treat these levels as follows. (Note, the terminology introduced in the first and second parts of my Quality Matters column for ACCU's Overload will be helpful in several instances.)

  • Emergency is used for (attempting to) record contract violations, i.e. the firing of an active runtime contract, indicating that the program is now behaving in contradiction to its design. According to the principle of irrecoverability, a program in this state must immediately terminate, and thus it is possible to see an emergency level message being the last, or one of the last, messages in the diagnostic logging sequence of a program that has faulted.
  • Alert is used for (attempting to) record practically-unrecoverable conditions, e.g. out of memory. It is customary to see an alert level message being the last, or one of the last, messages in the diagnostic logging sequence of a program that has ended processing in a non-normative manner.
  • Critical and error are used for conditions that usually indicate that the normative behaviour of the program cannot be achieved. There is some ambiguity as to the exact distinction to draw between them, and I'm still in two minds about it. Obviously, critical is more severe, and may be associated with conditions more likely to result in program failure than does those designated as error.
  • Warning is used for recording warning conditions.
  • Notice is used for logging information that is to be displayed in "normal" operation, e.g. "database connection achieved"
  • Informational is used for logging information that is useful when actively monitoring the health of a system, but that is not necessarily displayed as part of "normal" operation. Ideally it should be possible to turn on all logging of this level without exceeding the program's performance criteria.
  • Debug is used for debugging statements. Note that one of the important advanges of using Pantheios is that its high efficiency means that you don't have to make decisions about eliding certain statements at compile-time; they can instead be made at runtime, which is appropriate. Using Pantheios means eliminating #ifdef DEBUG from application code, forever!
Note: a couple of commercial clients have engaged us to provide customisations that define more levels than these. Feel free to get in touch for this, or other, commercial customisations.

I hope that's been helpful.

No comments:

Post a Comment