wiki:MapGuideRfc49

Context Navigation

Version 38 (modified by trevorwekel, 16 years ago) ( diff )
--

MapGuide RFC 49 - Enhance Server Error and Trace Logs

This page contains an change request (RFC) for the MapGuide Open Source project. More MapGuide RFCs can be found on the RFCs page.

Status

RFC Template Version	(1.0)
Submission Date	June 16, 2008
Last Modified	Trevor Wekel Timestamp
Author	Trevor Wekel
RFC Status	proposed
Implementation Status	in progress
Proposed Milestone	1.2, 2.0, 2.1
Assigned PSC guide(s)	Bruce Dechant
Voting History	June 23, 2008
+1
+0
-0
-1
no vote

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 only return the results of GetMessage(). 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()

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

Note: See TracWiki for help on using the wiki.

Download in other formats:

Plain Text