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 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 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 in MgProfilingService

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.

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.

Test Plan

Build/Run on Windows/Linux

Funding / Resources

Supplied by Autodesk