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	not ready for review
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,THREAD,ERROR,STACKTRACE
<2008-06-12T17:34:41> 			Administrator	4972
 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> 			Administrator	4856
 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: THREAD,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

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.

Funding/Resources

Autodesk