= !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, June 5,2011 ||
||Author|| Bruce Dechant, Ted Yang, Arthur Liu||
||RFC Status|| ready for review||
||Implementation Status||(under development)||
||Proposed Milestone|| 2.3 ||
||Assigned PSC guide(s)||Bruce Dechant||
||'''Voting History'''||Bruce Dechant, Jackie Ng, Zac Spitzer, Trevor Wekel, Tom Fukushima, Haris Kurtagic||
||+1||||
||+0||||
||-0||||
||-1||||
||no vote||||

== Overview ==

This RFC adds a !MgProfilingService which provides a skeleton for developers to profile existing !MapGuide APIs. !MgProfilingService aims to help developers and end users to identify resources that need to be optimized and performance bottlenecks. Two Profiling APIs will be implemented in this RFC and developers can add their own Profiling API into !MgProfilingService in the future. Also we will implement a UI in Site Admin to help the administrators easily execute a profiling and analyze the result.

== Motivation ==

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. And The UI will offer an visual way to perform the profiling and review the result. 

== 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);
}}}

Both of the above APIs will return an XML document that contains the profiling information gathered. The UI will be implemented in Site Admin as a php web page. There will be input fields for the required parameters of a profiling. The parameters can also be encoded into the URL so that the profiling UI could be easily integrated with some custom application of !MapGuide. 
After a profiling has finished with the input parameters, the result XML document will be returned and parsed.
Then the webpage will show the total render time for the map, and the render time of each layer in the map. Some additional layer information will be also showed to help the user analyze the results.The result could be exported as .csv file so that the user could do further analysis with other applications like Microsoft Excel. 

(We are not going to implement the Http API for !MgProfilingService)

== Information Gathered ==

The profiling information gathered for !ProfileRenderMap and !ProfileRenderDynamicOverlay:

!ProfileRenderMap:
{{{
Resource Id
Coordinate System
Extent
Scale
Image Format
Render Map Time
Render Layers Time
Render Selection Time
Render Watermars Time
Render Labels Time
Create Image Time
}}}

!ProfileRenderLayer:
{{{
Resource Id
Layer Type
Coordinate System
Current Scale Range
Filter
Render Time
}}}

!ProfileRenderWatermark:
{{{
Resource Id
Position Type
Stylization Time
}}}

!ProfileRenderLabels:
{{{
Render Labels Time
}}}


== XML Report / Schema ==

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

{{{
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.0.0">
  <xs:include schemaLocation="PlatformCommon-1.0.0.xsd"/>
  <xs:element name="ProfileResult" type="ProfileResultType"></xs:element>
  <xs:complexType name="ProfileResultType">
    <xs:choice>
      <xs:element name="ProfileRenderMap" type="ProfilerRenderMapType">
      </xs:element>
      <xs:element name="ProfileRenderDynamicOverlay" type="ProfilerRenderMapType">
      </xs:element>
      <xs:element name="ExtendedData1" type="ExtendedDataType" minOccurs="0"/>
    </xs:choice>
  </xs:complexType>
  <xs:complexType name="ProfilerRenderMapType">
    <xs:sequence>
      <xs:element name="ResourceId" type="xs:string"></xs:element>
      <xs:element name="CoordinateSystem" type="xs:string"></xs:element>
      <xs:element name="Extent" type="xs:string"></xs:element>
      <xs:element name="Scale" type="xs:double"></xs:element>
      <xs:element name="ImageFormat" type="xs:string"></xs:element>
      <xs:element name="RendererType" type="xs:string"></xs:element>
      <xs:element name="RenderTime" type="xs:double"></xs:element>
      <xs:element name="ProfileRenderLayers" type="ProfileRenderLayersType"></xs:element>
      <xs:element name="ProfileRenderSelection" type="ProfileRenderSelectionType"></xs:element>
      <xs:element name="ProfileRenderWatermarks" type="ProfileRenderWatermarksType"></xs:element>
      <xs:element name="ProfileRenderLabels" type="ProfileRenderLabelsType"></xs:element>
      <xs:element name="CreateImageTime" type="xs:double"></xs:element>
      <xs:element name="ExtendedData1" type="ExtendedDataType" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="ProfileRenderLayersType">
    <xs:sequence>
      <xs:element name="RenderTime" type="xs:double"></xs:element>
      <xs:element name="ProfileRenderLayer" type="ProfileRenderLayerType" minOccurs="0" maxOccurs="unbounded"></xs:element>
      <xs:element name="ExtendedData1" type="ExtendedDataType" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="ProfileRenderSelectionType">
    <xs:sequence>
      <xs:element name="RenderTime" type="xs:double"></xs:element>
      <xs:element name="Filter" type="xs:string"></xs:element>
      <xs:element name="ProfileRenderSelectedLayer" type="ProfileRenderLayerType" minOccurs="0" maxOccurs="unbounded"></xs:element>
      <xs:element name="ExtendedData1" type="ExtendedDataType" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="ProfileRenderWatermarksType">
    <xs:sequence>
      <xs:element name="RenderTime" type="xs:double"></xs:element>
      <xs:element name="ProfileRenderWatermark" type="ProfileRenderWatermarkType" minOccurs="0" maxOccurs="unbounded"></xs:element>
      <xs:element name="ExtendedData1" type="ExtendedDataType" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="ProfileRenderLabelsType">
    <xs:sequence>
      <xs:element name="RenderTime" type="xs:double"></xs:element>
      <xs:element name="ExtendedData1" type="ExtendedDataType" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="ProfileRenderLayerType">
    <xs:sequence>
      <xs:element name="ResourceId" type="xs:string"></xs:element>
      <xs:element name="LayerType" type="xs:string"></xs:element>
      <xs:element name="CoordinateSystem" type="xs:string"></xs:element>
      <xs:element name="ScaleRange" type="xs:string"></xs:element>
      <xs:element name="Filter" type="xs:string"></xs:element>
      <xs:element name="RenderTime" type="xs:double"></xs:element>
      <xs:element name="ExtendedData1" type="ExtendedDataType" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="ProfileRenderWatermarkType">
    <xs:sequence>
      <xs:element name="ResourceId" type="xs:string"></xs:element>
      <xs:element name="PositionType" type="xs:string"></xs:element>
      <xs:element name="RenderTime" type="xs:double"></xs:element>
      <xs:element name="ExtendedData1" type="ExtendedDataType" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>
</xs:schema>

}}}
Example of profiling rendering map process:
{{{
<?xml version="1.0" encoding="utf-8"?>
<ProfileResult>
  <ProfileRenderMap>
    <ResourceId>Library://Shaboygan.MapDefinition</ResourceId>
    <CoordinateSystem>LL84</CoordinateSystem>
    <Extent>43.73,-87.73,43.75,-87.72</Extent>
    <Scale>10000.00</Scale>
    <ImageFormat>PNG</ImageFormat>
    <RendererType>AGG</RendererType>
    <RenderTime>8.30</RenderTime>
    <ProfileRenderLayers>
      <RenderTime>5.00</RenderTime>
      <ProfileRenderLayer>
        <ResourceId>Library://Buildings.LayerDefinition</ResourceId>
        <LayerType>Vector</LayerType>
        <CoordinateSystem>CA-I</CoordinateSystem>
        <ScaleRange>ScaleRange1</ScaleRange>
        <Filter>FeatId &gt; 5</Filter>
        <RenderTime>3.00</RenderTime>
      </ProfileRenderLayer>
      <ProfileRenderLayer>
        <ResourceId>Library://Districts.LayerDefinition</ResourceId>
        <LayerType>Raster</LayerType>
        <CoordinateSystem>LL84</CoordinateSystem>
        <ScaleRange>ScaleRange2</ScaleRange>
        <Filter></Filter>
        <RenderTime>2.00</RenderTime>
      </ProfileRenderLayer>
    </ProfileRenderLayers>
    <ProfileRenderSelection>
      <RenderTime>0.25</RenderTime>
      <Filter>FeatId &lt; 100</Filter>
      <ProfileRenderSelectedLayer>
        <ResourceId>Library://Trees.LayerDefinition</ResourceId>
        <LayerType>Vector</LayerType>
        <CoordinateSystem>LL84</CoordinateSystem>
        <ScaleRange>ScaleRange1</ScaleRange>
        <Filter>FeatId &lt; 200</Filter>
        <RenderTime>0.10</RenderTime>
      </ProfileRenderSelectedLayer>
      <ProfileRenderSelectedLayer>
        <ResourceId>Library://Parcels.LayerDefinition</ResourceId>
        <LayerType>Vector</LayerType>
        <CoordinateSystem>LL84</CoordinateSystem>
        <ScaleRange>ScaleRange2</ScaleRange>
        <Filter></Filter>
        <RenderTime>0.15</RenderTime>
      </ProfileRenderSelectedLayer>
    </ProfileRenderSelection>
    <ProfileRenderWatermarks>
      <RenderTime>0.75</RenderTime>
      <ProfileRenderWatermark>
        <ResourceId>Library://Logo.WatermarkDefinition</ResourceId>
        <PositionType>Tile</PositionType>
        <RenderTime>0.6</RenderTime>
      </ProfileRenderWatermark>
      <ProfileRenderWatermark>
        <ResourceId>Library://Copyright.WatermarkDefinition</ResourceId>
        <PositionType>XY</PositionType>
        <RenderTime>0.15</RenderTime>
      </ProfileRenderWatermark>
    </ProfileRenderWatermarks>
    <ProfileRenderLabels>
      <RenderTime>1.25</RenderTime>
    </ProfileRenderLabels>
    <CreateImageTime>1</CreateImageTime>
  </ProfileRenderMap>
</ProfileResult>
}}}

== Implications ==

To profile an existing !MapGuide API, the profiling code will be injected into the original functions being profiled, which means !MgServerServices should be extended to accept a !MgProfileResult and the implementation of some APIs will be updated to support profiling. For example, to support profiling !RenderMap, !MgRenderingServerService needs to be extented by inheriting from !MgProfileManager which provides set/get method for !MgProfileResult.

The injected code will be executed only when the original code being invoked by !ProfilingService, so the the only impact to the original methods will be the extra if/else processing and nothing more.

[[Image(Class Diagram.png)]]

== Test Plan ==

!Build/Run on !Windows/Linux 

== Funding / Resources ==

Supplied by Autodesk