= !MapGuide RFC 49 - Enhance Server Error Reporting =

This page contains an change request (RFC) for the !MapGuide Open Source project.  
More !MapGuide RFCs can be found on the [wiki:MapGuideRfcs RFCs] page.


== Status == 
 
||RFC Template Version||(1.0)|| 
||Submission Date|| June 16, 2008 ||
||Last Modified|| Trevor Wekel [[Timestamp]]||
||Author||Trevor Wekel||
||RFC Status||adopted|| 
||Implementation Status||implemented||
||Proposed Milestone||2.1||
||Assigned PSC guide(s)||Bruce Dechant||
||'''Voting History'''||June 25, 2008||
||+1|| Bruce, Jason, Andy, Tom, Haris ||
||+0|| ||
||-0|| ||
||-1|| ||
||no vote|| Paul, Bob ||
 
== Overview ==

This proposal enhances the Server error and trace logs to include more detailed information about server operations.

== Motivation ==

The !MapGuide Server is a very complicated application and the current logs provide insufficient detail to determine the root cause of issues on production servers.  The proposed functionality enhances the core framework so that additional logging information can be added over a period time.

== Proposed Solution ==

Implement a classification system for log details controlled by a !LogsDetail parameter in serverconfig.ini:

{{{
[GeneralProperties]
LogsDetail = MappingService:3,FeatureService:1,RenderingService:2,ResourceService:0
}}}

The per-service classification scheme is defined as follows:

 * '''Level 0 - Errors without parameters'''
  * This is the default level of detail
  * Errors (exceptions) are logged without method parameters for the specified service
  * Warnings are not logged for this service
  * Traces are not logged for this service
  * __Note: Call parameter generation is disabled at this level to improve performance__
 * '''Level 1 - Warnings and Errors with parameters'''
  * Errors (exceptions) are logged with method parameters for the specified service
  * Warnings are logged with parameters for this service
  * Traces are not logged for this service
 * '''Level 2 - Trace, Warnings, and Errors'''
  * All Level 1 detail, plus
  * Traces with parameters are logged for published Service API calls
 * '''Level 3 - Internal Trace, Trace, Warnings, and Errors'''
  * All Level 2 detail, plus
  * Traces with parameters are logged for internal API calls

In the absence of a !LogsDetail entry in serverconfig.ini, each service will default to level 0.  By default !LogsDetail = "" so all services will default to level 0.  

In addition to the new classification scheme, the following improvements/changes will be made to the logging:
 * The current thread identifier will be added to both the error and trace logs.  This information is useful for call stack tracing.
 * STACKTRACE support also will be added to the trace log for warning and error messages.
 * The existing error log will be enhanced to include warning messages for a service and call parameters, if desired.
 * The existing trace log will also include error messages, warning messages and call parameters, if desired.  Each operation will have two entries tagged with BGN and END for timing purposes.

Here is a sample error log:

{{{
# Log Type: Error Log
# Log Parameters: CLIENT,CLIENTIP,USER,ERROR,STACKTRACE
<2008-06-12T17:34:41> 4972			Administrator	
 Warning: An exception occurred in FDO component.
        Geometry property value encountered!
 StackTrace:
  - MgStylizationUtil.ExceptionTrap() line 199 file .\GeometryAdapter.cpp	An exception occurred in FDO component.
Geometry property value encountered!
2008-06-16T12:32:42> 4856			Administrator	
 Error: Authentication failed.  Please enter a valid username and password.
 StackTrace:
  - MgSiteServiceHandler.ProcessOperation() line 83 file f:\mgdev1.2\os\server\src\services\site\SiteServiceHandler.cpp
  - MgOpAuthenticate.Execute() line 113 file f:\mgdev1.2\os\server\src\services\site\OpAuthenticate.cpp
  - MgServerSiteService.Authenticate(Session=,UserName=Administrator) line 699 file f:\mgdev1.2\os\server\src\services\site\ServerSiteService.cpp
  - MgSecurityManager.Authenticate() line 199 file f:\mgdev1.2\os\server\src\common\manager\SecurityManager.cpp	Authentication failed.  Please enter a valid username and password.

}}}

Here is a sample trace log:

{{{
# Log Type: Trace Log
# Log Parameters: INFO,STACKTRACE
<2008-06-12T17:34:41> 	4972	BGN	MgStylizationUtil.StylizeLayers	Map=Sheboygan,LayerId=Library://Samples/Sheboygan/Layers/Districts.LayerDefinition
<2008-06-12T17:34:41> 	4972	BGN	MgServerFeatureService.GetSpatialContexts	Id=Library://Samples/Sheboygan/Data/VotingDistricts.FeatureSource,ActiveOnly=0
<2008-06-12T17:34:41> 	4972	END	MgServerFeatureService.GetSpatialContexts
<2008-06-12T17:34:41> 	4972	BGN	MgServerFeatureService.SelectFeatures	Resource=Library://Samples/Sheboygan/Data/VotingDistricts.FeatureSource,ClassName=SDF_2_Schema:VotingDistricts,Options={{Operator=1}{GeomProp=Data}{GeomOp=10}{Geometry=POLYGON ((-87.783866628374042 43.691398128787803, -87.676641873488435 43.691398128787803, -87.676641873488435 43.797520000480297, -87.783866628374042 43.797520000480297, -87.783866628374042 43.691398128787803))}}
<2008-06-12T17:34:41> 	4972	END	MgServerFeatureService.SelectFeatures
<2008-06-12T17:34:41> 	4972	BGN	MgStylizationUtil.ExceptionTrap	Message=Geometry property value encountered!,File=.\GeometryAdapter.cpp,Line=199
<2008-06-12T17:34:41> 	4972	END	MgStylizationUtil.ExceptionTrap
<2008-06-12T17:34:41> 	4972
 Warning: An exception occurred in FDO component.
        Geometry property value encountered!
  - MgStylizationUtil.ExceptionTrap() line 199 file .\GeometryAdapter.cpp
<2008-06-12T17:34:41> 	4972	END	MgStylizationUtil.StylizeLayers
}}}

The existing !MgException class method !GetMessage(), !GetDetails(), and !GetStackTrace() will be enhanced as follows:
{{{
class MG_FOUNDATION_API MgException
{

PUBLISHED_API:

    ///////////////////////////////////////////////////////////////////////////
    /// \brief
    /// Retrieve the formatted exception message.  This is the localized and
    /// end user readable string.
    ///
    STRING GetMessage();

    ///////////////////////////////////////////////////////////////////////////
    /// \brief
    /// Retrieve the formatted exception details.  This includes the user readable string
    /// and the stack of method names with parameters which generated the error.  This
    /// string provides web application developers more information than the message.
    /// If a method does not have any parameters it will be omitted from the details. 
    ///
    STRING GetDetails();

    ///////////////////////////////////////////////////////////////////////////
    /// \brief
    /// Retrieve the formatted exception stack trace.  This includes file and line
    /// numbers, method names, and method parameters.  This string is useful for
    /// debugging MapGuide.
    ///
    STRING GetStackTrace();
}}}

To provide more appropriate end user information, the mapagent will return the results of !GetDetails().  Stack traces
are not very useful to end users.  Here are some sample exception messages generated from each call:

!GetMessage()
{{{
Session has expired or is invalid. Please log in again.
}}}

!GetDetails() - used for HTTP responses
{{{
Session has expired or is invalid. Please log in again.
- MgServerSiteService.Authenticate(Session=88d9658a-ffff-ffff-8000-005056c00008_en_7F0000020AFC0AFB0AFA,UserName=)
}}}

!GetStackTrace()
{{{
- MgSiteServiceHandler.ProcessOperation() line 83 file f:\mgdev1.2\os\server\src\services\site\SiteServiceHandler.cpp
- MgOpAuthenticate.Execute() line 113 file f:\mgdev1.2\os\server\src\services\site\OpAuthenticate.cpp
- MgServerSiteService.Authenticate(Session=88d9658a-ffff-ffff-8000-005056c00008_en_7F0000020AFC0AFB0AFA,UserName=) line 699 file f:\mgdev1.2\os\server\src\services\site\ServerSiteService.cpp
- MgSecurityManager.Authenticate() line 224 file f:\mgdev1.2\os\server\src\common\manager\SecurityManager.cpp
- MgSessionCache.GetSessionInfo() line 175 file f:\mgdev1.2\os\server\src\common\manager\SessionCache.cpp
}}}

== Implications ==

Level 0 matches the existing functionality set minus the trace log.  This means no information will be written to the trace log with the default settings.  To enable the trace log for a specific service, !LogsDetail should be set to level 2 or higher.

Since code change is required, not all operations or services will support the enhanced detail.  The additional detail will be implemented on an as required basis.

Internal C++ code constructs will be introduced within the !MapGuide Server code base to implement the enhanced functionality.  These constructs are internal only and beyond the scope of this RFC.  

== Test Plan ==

 * The detail discrimination mechanism will be tested for one service.
 * Testing will be performed at the highest level of detail for each service to ensure information is written to the logs.
 * Modifications to exception messages will be tested in PHP.  

== Funding/Resources ==

Autodesk

== Tickets ==

http://trac.osgeo.org/mapguide/ticket/641
http://trac.osgeo.org/mapguide/ticket/685