Debug Framework

[Ronan]

Since the debug system will be used by more people than the ones with CVS access, any comments?

Code: Select all

////////////////////////////////////////////////////////////////////////////////
//
//  System Name : ALFA Core Scripts
//     Filename : _debug_i
//      Version : 0.1
//         Date : 4/6/06
//       Author : Ronan
//
//  Local Variable Prefix = COR_DBG_
//
//  Description
//  These scripts provide tools to configure and run the debugging system.
//
//  Revision History
////////////////////////////////////////////////////////////////////////////////

////////////////////////////////////////////////////////////////////////////////
// Includes ////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////

// For the ArrayInt and ArrayString functions,
#include "nw_o0_itemmaker"

////////////////////////////////////////////////////////////////////////////////
// Constants ///////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////

// Do not print debug messages anywhere.
const int DEBUG_TARGET_NONE = 0x0000;

// Print debug messages to all DMs.
const int DEBUG_TARGET_DMS = 0x0001;

// Print debug messages to all PCs.
const int DEBUG_TARGET_PCS = 0x0010;

// Print debug messages to logfile.
const int DEBUG_TARGET_LOG = 0x0100;

// Print debug messages to a database.
const int DEBUG_TARGET_DB = 0x1000;

// Signifies a fatal error, keeping the associated system from performing its
// task.
const int DEBUG_LEVEL_FATAL = 1;

// Signifies a non-fatal error or odd behavior, which does not keep the
// associated system from performing its task.
const int DEBUG_LEVEL_WARNING = 2;

// Signifies general debugging information, not any sort of odd behavior or
// error.
const int DEBUG_LEVEL_INFO = 3;

// The prefix of all debug messages by level,
string DEBUG_MESSAGE_PREFIX_FATAL = "ERROR: ";
string DEBUG_MESSAGE_PREFIX_WARNING = "Warning: ";
string DEBUG_MESSAGE_PREFIX_INFO = "";

string LSA_DEBUG_SYSTEMS = "COR_DBG_S_";
string LIA_DEBUG_TARGETS_INFO = "COR_DBG_IT_";
string LIA_DEBUG_TARGETS_WARNING = "COR_DBG_WT_";
string LIA_DEBUG_TARGETS_FATAL = "COR_DBG_FT_";

// The default "catch-all" system for debug messages.
const int DEBUG_SYSTEM_DEFAULT = 0;
const string DEBUG_SYSTEM_DEFAULT_PREFIX = "";
const int DEBUG_SYSTEM_INFO_TARGETS = DEBUG_TARGET_NONE;
const int DEBUG_SYSTEM_WARNING_TARGETS = DEBUG_TARGET_NONE;
const int DEBUG_SYSTEM_FATAL_TARGETS = DEBUG_TARGET_LOG;

////////////////////////////////////////////////////////////////////////////////
// Structures //////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////

////////////////////////////////////////////////////////////////////////////////
// Global Variables ////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////

// Current number of debugging systems added.
int numSystems;

////////////////////////////////////////////////////////////////////////////////
// Function Prototypes /////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////////

// This sends a debug message to the specified target(s).
// Generally PrintDebug() should be used, not this function.
void SendDebugMessage(string message, int targets);

// Prints a debug message from the system id specified with the warning level
// specified. To create a system id, see the CreateDebugSystem() function.
// Valid warning levels are:
//
// DEBUG_LEVEL_FATAL
// Signifies a fatal error, keeping the associated system from performing its
// task.
//
// DEBUG_LEVEL_WARNING
// Signifies a non-fatal error or odd behavior, which does not keep the
// associated system from performing its task.
//
// DEBUG_LEVEL_INFO
// Signifies general debugging information, not any sort of odd behavior or
// error.
void PrintDebugMessage(string message, int systemId = DEBUG_SYSTEM_DEFAULT, int level = DEBUG_LEVEL_INFO);

// Returns a systemId integer which refers to the debugging messages for the
// system.
// prefix is the prefix printed on all debugging messages printed.
// The target parameters are bit-wise variables indicating the places where
// debug messages are sent for each debug warning level (see  the
// PrintDebugMessage() function. For example,
// int spawnId = CreateSystemId("Spawn system: ", DEBUG_TARGET_NONE,
//                              DEBUG_TARGET_LOG,
//                              DEBUG_TARGET_LOG | DEBUG_TARGET_DMS );
// This call creates a system where no informational messages are printed,
// warning messages go to the log, and fatal errors are sent to all DMs and sent
// to the log. The targets of the three debug levels can be changed in-game by
// a DM-tool as well.
int CreateDebugSystem(string prefix, int infoTargets = DEBUG_TARGET_NONE, int warningTargets = DEBUG_TARGET_LOG, int fatalTargets = DEBUG_TARGET_LOG);

// Initializes the debugging system. This function MUST be called from the
// OnModuleLoad event for the debugging system to function correctly.
void InitializeDebugging();

[ç i p h é r]

Moved to separate post.

The only thing I think we should add is a database log option. Otherwise, you seem to have the bases well covered.

P.S. void CorDebugOnModuleLoad()...should that be CoreDebug...?

[Ronan]

Just edited, as I've made some changes. Its more powerfull now, as each debug message is assigned an importance level (informative, warning, or fatal error). This way a DM could use a tool to select a system for debugging, then toggle what sort of information he'd like to hear (maybe only errors, maybe everything, etc).

The downside is its more difficult for the coder to print these messages, because each message needs a system id (integer returned which each system is initialized) and a warning level (DEBUG_LEVEL_* constants).

Thoughts? I don't see a need for a "simple" debugging system, since such a thing wouldn't provide any advantages over simple use of SendMessageToAllDMs() or SendMessageToPC().

[ç i p h é r]

I presume default messaging behavior will be defined somewhere? Aside from that, I think the flexibility is a very clever addition and only adds a minor increase in overhead.

What's the purpose of the prefix? Linking back to the actual system/subsystem that generated the message?

My only concern is the use of abbreviations/acronyms. I think that can be something of a hurdle for debugging purposes. You don't want to have to do any extraneous lookups or be stymied by obscure references when puzzling over a problem. Clarity is worth the extra keystrokes it takes to code. To that extent, I suppose there could be a verbose option to force certain messaging behavior. But, I may just not be clear on the intended purpose.

Along the same vein, what about categorization options (primary & secondary) for debug messages? That could help when organizing or reporting on logs/db records while "offline" (ie not monitoring in real time). So let's say we want to add some debug messaging for our login processing....a primary category might be "LOGIN" and a secondary category might be "AUTHENTICATION". You can then review, sort, purge, or whatever all these logs if you had an interest in that particular aspect of the system (visa's/passports in this case).

Other than that, looks real good.

[Ronan]

I presume default messaging behavior will be defined somewhere? Aside from that, I think the flexibility is a very clever addition and only adds a minor increase in overhead.

Good point, I can add a catch-all system id and changed the PrintDebugMessage function to something like,

Code: Select all

PrintDebugMessage(string message, int level = DEBUG_LEVEL_INFO, int systemId = DEFAULT_DEBUG_SYSTEM);

What's the purpose of the prefix? Linking back to the actual system/subsystem that generated the message?

Yeah, just a way to ID which system the message came from, basically.

My only concern is the use of abbreviations/acronyms. I think that can be something of a hurdle for debugging purposes. You don't want to have to do any extraneous lookups or be stymied by obscure references when puzzling over a problem. Clarity is worth the extra keystrokes it takes to code. To that extent, I suppose there could be a verbose option to force certain messaging behavior. But, I may just not be clear on the intended purpose.

Where do you see acronyms? I don't think there are any in what are ment to be the "public" functions of this script. I do begin local variable names with acronyms: LS = local string, LSA = local string array, LI = local object, etc.

Along the same vein, what about categorization options (primary & secondary) for debug messages? That could help when organizing or reporting on logs/db records while "offline" (ie not monitoring in real time). So let's say we want to add some debug messaging for our login processing....a primary category might be "LOGIN" and a secondary category might be "AUTHENTICATION". You can then review, sort, purge, or whatever all these logs if you had an interest in that particular aspect of the system (visa's/passports in this case).

A hierarchy? I can see the benifit, but I'm not sure its worth the complexity over this, is it?

Code: Select all

CreateDebugSystem("Login, auth: ", someTargets, someTargets, someTargets);

[ç i p h é r]

Where do you see acronyms? I don't think there are any in what are ment to be the "public" functions of this script. I do begin local variable names with acronyms: LS = local string, LSA = local string array, LI = local object, etc.

Yeah, I was just referring to the prefixes in the messaging, so if prefix is part of the script filename, then that's useful. You can easily look up/recognize the scripts that generated the message.

A hierarchy? I can see the benifit, but I'm not sure its worth the complexity over this, is it?

Code: Select all

CreateDebugSystem("Login, auth: ", someTargets, someTargets, someTargets);

I was thinking more like function(primary, secondary, message, targets, targets, targets). Not sure if it adds complexity but it would introduce a bit more organization in stored debug messages. Not a necessity, just a thought. Maybe the prefix already covers this well enough.

[Ronan]

A hierarchy? I can see the benifit, but I'm not sure its worth the complexity over this, is it?

Code: Select all

CreateDebugSystem("Login, auth: ", someTargets, someTargets, someTargets);

I was thinking more like function(primary, secondary, message, targets, targets, targets). Not sure if it adds complexity but it would introduce a bit more organization in stored debug messages. Not a necessity, just a thought. Maybe the prefix already covers this well enough.

Unless I'm misunderstanding you (and I could be) I think it does.