= !MapGuide RFC 110 - Profiling API enhancement =

This page contains a 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|| February 23,2011 ||
||Last Modified|| Bruce Dechant, February 23,2011 ||
||Author|| Bruce Dechant||
||RFC Status|| draft||
||Implementation Status||(pending)||
||Proposed Milestone|| 2.3 ||
||Assigned PSC guide(s)||Bruce Dechant||
||'''Voting History'''|| ||
||+1||||
||+0||||
||-0||||
||-1||||
||no vote||||

== Overview ==

This RFC adds some profiling APIs to !MapGuide to help identify resources that need to be optimized and performance bottlenecks.

== Motivation ==

Provide some profiling APIs that would generate an XML report that could be analyzed to help determine if any resources need to be optimized or if there are performance bottlenecks in the code that need to be looked at.

== Proposed Solution ==

The following NEW APIs will be added to the offical API (PHP, Java and .Net):

{{{
MgByteReader* ProfileRenderMap(MgMap* map,
                               MgSelection* selection,
                               MgCoordinate* center,
                               double scale,
                               INT32 width,
                               INT32 height,
                               MgColor* backgroundColor,
                               CREFSTRING format,
                               bool bKeepSelection,
                               INT32 runs);
}}}


{{{
MgByteReader* ProfileRenderDynamicOverlay(MgMap* map,
                                          MgSelection* selection,
                                          MgRenderingOptions* options,
                                          INT32 runs);
}}}

{{{
MgByteReader* ProfileRenderMapLegend(MgMap* map,
                                     INT32 width,
                                     INT32 height,
                                     MgColor* backgroundColor,
                                     CREFSTRING format,
                                     INT32 runs);
}}}

{{{
MgByteReader* ProfileResource(MgResourceIdentifier* resource, INT32 runs)
}}}

'''Note: The results of the !ProfileResource() API depends on the type of resource profiled.'''

The resource types supported by the !ProfileResource() API are:
{{{
MapDefinition
LayerDefinition
FeatureSource
}}}

All of the above APIs will return an XML document that contains the profiling information gathered.

== Information Gathered ==

The profiling information gathered will contain a collection of the items below depending on what is applicable.

!MapDefinition:
{{{
Render Time
Initial scale ranges
Initial layers
Base layers
Coordinate System
Legend details
Data extents
}}}

!LayerDefinition:
{{{
Render Time
Query Time
Number of Features
Feature Class
Properties
Data Extents
Filters
Scale Ranges
Theme Rules
Tooltip
URL
Watermark (If applicable)
}}}

!FeatureSource:
{{{
Initial FDO Connection Time
Subsequent FDO Connection Time (Cache hits)
Initial DescribeSchema Time
Subsequent DescribeSchema Time (Cache hits)
Remaining cached FDO information 
Joins
Calculations
Coordinate System of Data (Indicate if a CS transformation is needed. Only applies if we are profiling a map.)
}}}

== XML Report / Schema ==

The generated XML report document will be defined by the following schema.

'''TBD XML document schema'''

Example of profiling a !MapDefintion: (Work in progress)
{{{
Map Summary
  Layer(s) Summary
  Layer(s) Details 
    Feature Source(s) Summary
    Feature Source(s) Details
}}}

== Implications ==

None as these are new APIs.

== Test Plan ==

!Build/Run on !Windows/Linux 

== Funding / Resources ==

Supplied by Autodesk