= !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 an !MgProfilingService which provides 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);
}}}


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

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

{{{
MgByteReader* ProfileResource(MgResourceIdentifier* resource)
}}}

'''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:
{{{
Resource Id
Coordinate System
Extents
Layer Count
Watermark Count
Image Format
Render Map Time
Render Layers Time
Render Selection Time
Render Watermars Time
Render Labels Time
Create Image Time
}}}

!LayerDefinition:
{{{
Resource Id
Schema Name
Feature Class Name
Scale Ranges
Coordinate System
Filter
Number of Features
Render Time
Get Idendity Properties Time
Coordinate System Transform Time (Only applies if we are profiling a map rendering process.)
Query Features Time
Stylization Time
}}}

!FeatureSource:
{{{
Resource Id
Provider Time
IsFromCache
Joins
Calculations
Open Connection Time
Describe Schemas Time
SelectFeatures Time
}}}

!WatermarkDefinition
{{{
Resource Id
Position Type
Stylization Time
}}}

Labels:
{{{
Label Count
Render Labels Time
}}}


== XML Report / Schema ==

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

'''TBD XML document schema'''

Example of profiling rendering map process: (Work in progress)
{{{
-MapProfileResult
  -Map Summary
    Resource Id
    Resource Id
    Coordinate System
    Extents
    Layer Count
    Watermark Count
    Image Format
    Render Map Time
    Render Layers Time
    Render Selection Time
    Render Watermars Time
    Render Labels Time
    Create Image Time
  -Map Details
    -LayerProfileResult
      -Layer(s) Summary
        Resource Id
        Schema Name
        Feature Class Name
        Scale Ranges
        Coordinate System
        Filter
        Number of Features
        Render Time
        Get Idendity Properties Time
        Coordinate System Transform Time (Only applies if we are profiling a map rendering process.)
        Query Features Time
        Stylization Time
      -Layer(s) Details 
        +Feature Source(s) Summary
        +Feature Source(s) Details
    -SelectionProfileResult
      Layer(s) Summary
      Layer(s) Details 
    -WatermarkProfileResult
      -Watermark(s) Summary
        Resource Id
        Position Type
        Stylization Time
      +Watermark(s) Details
    -LabelsProfileResult
      -Labels Summary
        Label Count
        Render Labels Time

}}}

== Implications ==

Solution 1.
Copy the implementation of profiling related APIs to !MgServerProfilingService and add profiling code into the copied version, for example, copy the implementation of !RenderMap in !MgServerRenderingService(and all other MG server APIs invoked in !RenderMap) to !MgServerProfilingService. The advantage and disadvantage of this implementation is obvious: less influence on the origial implementation but heavy maintainence to do in the future.

Solution 2.
Inject the profiling code into the functions being profiled, which means !MgServerServices should be extended to accept a !ProfileResult and the implementation of some APIs will updated to support profiling. For example, to support profiling !RenderMap, all the !MgServerServices in the !RenderMap workflow will be affected - !MgServerRenderingService, !MgServerResourceService, !MgServerFeatureService, !MgServerDescribeSchema, !MgServerSelectFeatures, etc.

For both solustions, how many code should be copied or updated will be decided by how detailed information should be gathered.

== Test Plan ==

!Build/Run on !Windows/Linux 

== Funding / Resources ==

Supplied by Autodesk