= !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 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

== 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.

== 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.

(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, !MgRenderingServerServices needs to be extented by inheriting from !MgProfileManager which provides set/get method for !MgProfileResult.

[[Image(Class Diagram.png)]]

== Test Plan ==

!Build/Run on !Windows/Linux 

== Funding / Resources ==

Supplied by Autodesk