2.2.3.3 Report Schema Formatting

Article
06/24/2021

This section contains the XSD for the IDataManager ReportSchema property.

   
  <?xml version="1.0" encoding="utf-8"?>
  <xs:schema targetNamespace="http://schemas.microsoft.com/diagnostics/2007/02/tracerpt" elementFormDefault="qualified" xmlns:man="http://schemas.microsoft.com/diagnostics/2007/02/tracerpt" xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:simpleType name="GUIDType">
      <xs:restriction base="xs:string">
        <xs:pattern value="\{[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-
          [0-9a-fA-F]{12}\}" />
      </xs:restriction>
    </xs:simpleType>
    <xs:element name="Report">
      <xs:annotation>
        <xs:documentation>Contains the specification of the report schema as well as 
          localization information.</xs:documentation>
      </xs:annotation>
      <xs:complexType>
        <xs:sequence minOccurs="1" maxOccurs="1">
          <xs:element ref="man:Import" minOccurs="0" maxOccurs="unbounded" />
          <xs:element name="Sections" minOccurs="0" maxOccurs="1">
            <xs:annotation>
              <xs:documentation>Starting tag for &lt;Section&gt;, which is the logical 
                category for tables.Tables from different providers can be grouped 
                under one section.  For example, a TCP/IP table belongs to 
                &quot;Network&quot; section and &quot;UDP/IP&quot; table also belongs 
                to &quot;Network&quot; section.There are one more &lt;Section&gt; 
                under &lt;Sections&gt;.</xs:documentation>
            </xs:annotation>
            <xs:complexType>
              <xs:sequence minOccurs="1" maxOccurs="1">
                <xs:element name="Section" minOccurs="1" maxOccurs="unbounded">
                  <xs:annotation>
                    <xs:documentation>Logical category for tables in 
                      the report.</xs:documentation>
                  </xs:annotation>
                  <xs:complexType>
                    <xs:sequence minOccurs="1" maxOccurs="unbounded">
                      <xs:choice minOccurs="1" maxOccurs="1">
                        <xs:element ref="man:EventTable" />
                        <xs:element ref="man:CounterTable" />
                      </xs:choice>
                    </xs:sequence>
                    <xs:attribute name="name" type="xs:string" use="required">
                      <xs:annotation>
                        <xs:documentation>Section title (localizable).</xs:documentation>
                      </xs:annotation>
                    </xs:attribute>
                    <xs:attribute name="key" type="xs:nonNegativeInteger" use="required">
                      <xs:annotation>
                        <xs:documentation>Used to sort the sections.</xs:documentation>
                      </xs:annotation>
                    </xs:attribute>
                    <xs:attribute name="note" type="xs:string" use="optional">
                      <xs:annotation>
                        <xs:documentation>Note text (localizable).</xs:documentation>
                      </xs:annotation>
                    </xs:attribute>
                  </xs:complexType>
                </xs:element>
              </xs:sequence>
            </xs:complexType>
          </xs:element>
          <xs:element name="StringTable" minOccurs="0" maxOccurs="1">
            <xs:annotation>
              <xs:documentation>
                  Defines the localized strings.  This tag is optional under &lt;Report&gt;.
                  All localizable strings in the manifest serves as a string ID 
                  corresponding to the string in the string table. If there is no matching
                  string in the string table, the localizable string won't be translated,
                  but shows the original content instead.
              </xs:documentation>
            </xs:annotation>
            <xs:complexType>
              <xs:sequence>
                <xs:element minOccurs="1" maxOccurs="unbounded" name="String">
                  <xs:annotation>
                    <xs:documentation>
                        Defines each localized string. This tag is required 
                        under &lt;StringTable&gt;.</xs:documentation>
                  </xs:annotation>
                  <xs:complexType>
                    <xs:simpleContent>
                      <xs:extension base="xs:string">
                        <xs:attribute name="ID" type="xs:string" use="required">
                          <xs:annotation>
                            <xs:documentation>The ID of the localized string.  
                              Referenced by the name attribute of the Report, EventTable,
                              CounterTable and Column elements.
                            </xs:documentation>
                          </xs:annotation>
                        </xs:attribute>
                        <xs:attribute name="loc.comment" type="xs:string" use="optional">
                          <xs:annotation>
                            <xs:documentation>Comment used to inform the person 
                                localizing this string as to how this string is 
                                used.</xs:documentation>
                          </xs:annotation>
                        </xs:attribute>
                      </xs:extension>
                    </xs:simpleContent>
                  </xs:complexType>
                </xs:element>
              </xs:sequence>
            </xs:complexType>
          </xs:element>
        </xs:sequence>
        <xs:attribute name="version" type="xs:unsignedByte" use="required">
          <xs:annotation>
            <xs:documentation>Report version.</xs:documentation>
          </xs:annotation>
        </xs:attribute>
        <xs:attribute name="name" type="xs:string" use="required">
          <xs:annotation>
            <xs:documentation>Report title (localizable).</xs:documentation>
          </xs:annotation>
        </xs:attribute>
        <xs:attribute name="threshold" type="xs:nonNegativeInteger" use="optional">
          <xs:annotation>
            <xs:documentation>Number of rows to display.  By default it is 
              25.</xs:documentation>
          </xs:annotation>
        </xs:attribute>
      </xs:complexType>
    </xs:element>
    <xs:element name="Import">
      <xs:annotation>
        <xs:documentation>This is used to avoid repeating definitions if the report is 
            already defined in other files.  There will be multiple &lt;Report&gt; 
            defining the report attributes with this feature; however, only the 
            &lt;Report&gt;attribute in the file will be used.  Other &lt;Report&gt; 
            attributes written in other imported files will simply be 
            ignored.</xs:documentation>
      </xs:annotation>
      <xs:complexType>
        <xs:attribute name="file" type="xs:string" use="required">
          <xs:annotation>
            <xs:documentation>File path (absolute or relative) to other report 
              file</xs:documentation>
          </xs:annotation>
        </xs:attribute>
      </xs:complexType>
    </xs:element>
    <xs:element name="EqualJoin">
      <xs:annotation>
        <xs:documentation>
          Specifies the relationship between two different data sources.
          Event data source is identified by (providerID, payloadId, version).
          The idea is similar to SQL table equal join. 
          Note that we only allow two providers in a join operation and thus fields under 
          &lt;EqualJoin&gt; need to come from two different data sources.</xs:documentation>
      </xs:annotation>
      <xs:complexType>
        <xs:sequence minOccurs="2" maxOccurs="2">
          <xs:element name="EventJoinField" minOccurs="1" maxOccurs="1">
            <xs:annotation>
              <xs:documentation>
                Specifies the data source from an event provider for join operation.
                It is a subset of &lt;EventField&gt;.  
                In addition, it cannot use a composite field</xs:documentation>
            </xs:annotation>
            <xs:complexType>
              <xs:complexContent>
                <xs:extension base="man:BaseEventField">
                </xs:extension>
              </xs:complexContent>
            </xs:complexType>
          </xs:element>
        </xs:sequence>
      </xs:complexType>
    </xs:element>
    <xs:element name="SubTable">
      <xs:annotation>
        <xs:documentation>
          Defines the child table of a parent table.  
          A child table can be used to display more detailed information than its 
          parent table.  
          The report does not expand the child table, but shows a &quot;+&quot; sign.  
          Users can choose to read the child table by clicking the &quot;+&quot; sign.  
          This tag is optional under &lt;table&gt;
          &lt;Column&gt; is required under &lt;SubTable&gt;.  
          &lt;Column&gt; fields need to come from the same provider(s) as &lt;table&gt; has.  
          The &lt;Column&gt; under &lt;SubTable&gt; is almost the same as &lt;Column&gt;
          under &lt;EventTable&gt;, except groupby and aggregate cannot apply to subtable
          columns.</xs:documentation>
      </xs:annotation>
      <xs:complexType>
        <xs:sequence>
          <xs:element ref="man:Column" minOccurs="1" maxOccurs="unbounded"/>
        </xs:sequence>
      </xs:complexType>
    </xs:element>
    <xs:element name="Column">
      <xs:annotation>
        <xs:documentation>Defines each column of the table. This tag is required under 
            &lt;EventTable&gt; and &lt;SubTable&gt;.</xs:documentation>
      </xs:annotation>
      <xs:complexType>
        <xs:sequence minOccurs="1" maxOccurs="1">
          <xs:element name="EventField" minOccurs="1" maxOccurs="1">
            <xs:annotation>
              <xs:documentation>Specifies the data source from an event 
                  provider.</xs:documentation>
            </xs:annotation>
            <xs:complexType>
              <xs:complexContent>
                <xs:extension base="man:BaseEventField">
                  <xs:attribute name="aggregate" use="optional">
                    <xs:annotation>
                      <xs:documentation>
                        Count the column values and show the calculation in the bucket.
                        A field with aggregate attribute is defined as an aggregation 
                        field.
                        This aggregate attribute also only applies to numeric fields.
                        Aggregate functions perform a calculation on a set of values 
                        and return a single value.
                        Aggregation needs to be used with the groupby column, which is 
                        defined with the groupby attribute value is true.
                        We put the following restrictions on the use of aggregation:
                        This groupby column cannot have an aggregation field.
                        A table with group by column(s) MUST has other columns with 
                        aggregation fields.
                        Aggregation can only apply to numeric fields.
                        We define such a table as an aggregation table: groupby 
                        column(s) and one or more aggregation columns.
                        Note that not all numeric fields can be aggregated in a 
                        meaningful way, for example, aggregation on error code or disk 
                        ID does not make sense in a report.
                        As described in &lt;Column&gt; section, aggregate attribute in
                        &lt;EventField&gt; cannot apply to &lt;EventField&gt; under 
                        &lt;SubTable&gt;, either
                      </xs:documentation>
                    </xs:annotation>
                    <xs:simpleType>
                      <xs:restriction base="xs:token">
                        <xs:enumeration value="total">
                          <xs:annotation>
                            <xs:documentation>The sum of the column 
                                values.</xs:documentation>
                          </xs:annotation>
                        </xs:enumeration>
                        <xs:enumeration value="average">
                          <xs:annotation>
                            <xs:documentation>The sum divided by the number of 
                              events.</xs:documentation>
                          </xs:annotation>
                        </xs:enumeration>
                        <xs:enumeration value="rate">
                          <xs:annotation>
                            <xs:documentation>The sum divided by the trace duration.</xs:documentation>
                          </xs:annotation>
                        </xs:enumeration>
                      </xs:restriction>
                    </xs:simpleType>
                  </xs:attribute>
                  <xs:attribute name="note" type="xs:string" use="optional">
                    <xs:annotation>
                      <xs:documentation>Note text (localizable).</xs:documentation>
                    </xs:annotation>
                  </xs:attribute>
                </xs:extension>
              </xs:complexContent>
            </xs:complexType>
          </xs:element>
        </xs:sequence>
        <xs:attribute name="name" type="xs:string" use="required">
          <xs:annotation>
            <xs:documentation>The title of the column (localizable, unique in 
              the table)</xs:documentation>
          </xs:annotation>
        </xs:attribute>
        <xs:attribute name="align" use="optional">
          <xs:annotation>
            <xs:documentation>Alignment of the column value. The default is 
              right.</xs:documentation>
          </xs:annotation>
          <xs:simpleType>
            <xs:restriction base="xs:token">
              <xs:enumeration value="left" />
              <xs:enumeration value="right" />
            </xs:restriction>
          </xs:simpleType>
        </xs:attribute>
        <xs:attribute name="format" type="xs:string" use="optional">
          <xs:annotation>
            <xs:documentation>An XSLT number format mask.</xs:documentation>
          </xs:annotation>
        </xs:attribute>
        <xs:attribute name="sort" use="optional">
          <xs:annotation>
            <xs:documentation>Primary or secondary sorting column.</xs:documentation>
          </xs:annotation>
          <xs:simpleType>
            <xs:restriction base="xs:token">
              <xs:enumeration value="primary" />
              <xs:enumeration value="secondary" />
            </xs:restriction>
          </xs:simpleType>
        </xs:attribute>
        <xs:attribute name="order" use="optional">
          <xs:annotation>
            <xs:documentation>Defines the order of rows shown in the table.  
              The default is descending. There will be at most one primary sort column and 
            one secondary sort column.</xs:documentation>
          </xs:annotation>
          <xs:simpleType>
            <xs:restriction base="xs:token">
              <xs:enumeration value="ascending">
                <xs:annotation>
                  <xs:documentation>Small to big A-Z or 0-9.</xs:documentation>
                </xs:annotation>
              </xs:enumeration>
              <xs:enumeration value="descending">
                <xs:annotation>
                  <xs:documentation>Big to small Z-A or 9-0</xs:documentation>
                </xs:annotation>
              </xs:enumeration>
            </xs:restriction>
          </xs:simpleType>
        </xs:attribute>
        <xs:attribute name="outType" type="xs:string" use="optional">
          <xs:annotation>
            <xs:documentation>An XSD type descriptor.</xs:documentation>
          </xs:annotation>
        </xs:attribute>
        <xs:attribute name="visible" type="xs:boolean" use="optional">
          <xs:annotation>
            <xs:documentation>Describe whether this column is visible in the rendered 
              view of the table.  Default is true.</xs:documentation>
          </xs:annotation>
        </xs:attribute>
        <xs:attribute name="summary" use="optional">
          <xs:annotation>
            <xs:documentation>Put table footer for all the column values. The possible 
              value of summary attribute is total and average. Note that this attribute
              only applies to the numeric fields.</xs:documentation>
          </xs:annotation>
          <xs:simpleType>
            <xs:restriction base="xs:token">
              <xs:enumeration value="total">
                <xs:annotation>
                  <xs:documentation>Sum up the rows of the column.</xs:documentation>
                </xs:annotation>
              </xs:enumeration>
              <xs:enumeration value="average">
                <xs:annotation>
                  <xs:documentation>Calculate the average of the rows of the 
                    column.</xs:documentation>
                </xs:annotation>
              </xs:enumeration>
            </xs:restriction>
          </xs:simpleType>
        </xs:attribute>
        <xs:attribute name="groupby" type="xs:boolean" use="optional">
          <xs:annotation>
            <xs:documentation>Related to aggregation function of the &lt;EventField&gt;
                element. 
              It can only apply to &lt;Column&gt; under &lt;EventTable&gt;.  
              They are not applicable to &lt;Column&gt; under &lt;SubTable&gt;
            </xs:documentation>
          </xs:annotation>
        </xs:attribute>
        <xs:attribute name="note" type="xs:string" use="optional">
          <xs:annotation>
            <xs:documentation>Note text (localizable).</xs:documentation>
          </xs:annotation>
        </xs:attribute>
      </xs:complexType>
    </xs:element>
    <xs:element name="CounterTable">
      <xs:annotation>
        <xs:documentation>
          Defines the basic building block, the table, in a report for counter data source.
          Every attribute is the same as &lt;EventTable&gt;, except an additional
          attribute, object, is added.  
          Every counter table will have four or five columns: counter, instance, mean, min,
          and max.  
          If the object has instances, instance column will be added to the table.  
          Otherwise, instance column is not shown.</xs:documentation>
      </xs:annotation>
      <xs:complexType>
        <xs:sequence minOccurs="0" maxOccurs="unbounded">
          <xs:choice minOccurs="1" maxOccurs="1">
            <xs:element ref="man:Exclude" minOccurs="1" maxOccurs="1" />
            <xs:element ref="man:Include" minOccurs="1" maxOccurs="1" />
          </xs:choice>
        </xs:sequence>
        <xs:attribute name="name" type="xs:string" use="required">
          <xs:annotation>
            <xs:documentation>Table title (localizable).</xs:documentation>
          </xs:annotation>
        </xs:attribute>
        <xs:attribute name="topic" type="xs:string" use="required">
          <xs:annotation>
            <xs:documentation>Topic title (localizable).</xs:documentation>
          </xs:annotation>
        </xs:attribute>
        <xs:attribute name="object" type="xs:string" use="required">
          <xs:annotation>
            <xs:documentation>Counter object name.</xs:documentation>
          </xs:annotation>
        </xs:attribute>
        <xs:attribute name="level" use="optional">
          <xs:annotation>
            <xs:documentation>
              Range 1 to 5. Used to control whether this table will be generated or not.
              If the level of the table is less than or equal to the tracerpt system level,
              this table will be generated.
              By setting system level in tracerpt by a command-line switch, only those 
              tables with proper level will be generated.
              The table level and tracerpt system level are 1 by default.
            </xs:documentation>
          </xs:annotation>
          <xs:simpleType>
            <xs:restriction base="xs:integer">
              <xs:minInclusive value="1"/>
              <xs:maxInclusive value="5"/>
            </xs:restriction>
          </xs:simpleType>
        </xs:attribute>
        <xs:attribute name="key" type="xs:positiveInteger" use="optional">
          <xs:annotation>
            <xs:documentation>Used to sort the tables.</xs:documentation>
          </xs:annotation>
        </xs:attribute>
        <xs:attribute name="note" type="xs:string" use="optional">
          <xs:annotation>
            <xs:documentation>Note text (localizable).</xs:documentation>
          </xs:annotation>
        </xs:attribute>
        <xs:attribute name="threshold" type="xs:positiveInteger" use="optional">
          <xs:annotation>
            <xs:documentation>Number of rows in the table.</xs:documentation>
          </xs:annotation>
        </xs:attribute>
      </xs:complexType>
    </xs:element>
    <xs:element name="Exclude">
      <xs:annotation>
        <xs:documentation>
          Specifies the exclusive counter name pattern string.
          The object counter table will not include these counters in the rows.
          For example, &lt;Exclude counter=&quot;i/avg*/&quot;/&lt; will exclude those 
          counter names with the pattern: 
          starting with string &quot;avg&quot; (case-insensitive comparison).
        </xs:documentation>
      </xs:annotation>
      <xs:complexType>
        <xs:attribute name="counter" type="xs:string" use="optional">
          <xs:annotation>
            <xs:documentation>The counter name pattern string. 
              Pattern Modifiers: 
              i - Case-insensitive. 
              Pattern Matches: 
              / - Starting and ending sequence. 
              ? - Any one character. 
              * - Zero or more characters. 
              \ - Escape character. 
            </xs:documentation>
          </xs:annotation>
        </xs:attribute>
        <xs:attribute name="column" type="xs:string" use="optional">
          <xs:annotation>
            <xs:documentation>The name of the column to exclude.  Options are:
              machine, min, max, or mean.</xs:documentation>
          </xs:annotation>
        </xs:attribute>
      </xs:complexType>
    </xs:element>
    <xs:element name="Include">
      <xs:annotation>
        <xs:documentation>
          Specifies the inclusive instance name pattern string.
          The object counter table will only include these counters in the rows.
          For example, &lt;Include instance=&quot;i/cmd*/&quot;/&gt; will only include 
          those counters with the instance pattern string: 
          starting with string &quot;cmd&quot; (case-insensitive comparison).
        </xs:documentation>
      </xs:annotation>
      <xs:complexType>
        <xs:attribute name="instance" type="xs:string" use="required">
          <xs:annotation>
            <xs:documentation>The instance name pattern string. 
              Pattern Modifiers:
              i - Case-insensitive.
              Pattern Matches:
              / - Starting and ending sequence.
              ? - Any one character.
              * - Zero or more characters.
              \ - Escape character.
            </xs:documentation>
          </xs:annotation>
        </xs:attribute>
      </xs:complexType>
    </xs:element>
    <xs:element name="EventTable">
      <xs:annotation>
        <xs:documentation>The basic building block in a report for an event data 
          source.</xs:documentation>
      </xs:annotation>
      <xs:complexType>
        <xs:sequence>
          <xs:element ref="man:Column" minOccurs="1" maxOccurs="unbounded" />
          <xs:element ref="man:EqualJoin" minOccurs="0" maxOccurs="1"/>
          <xs:element ref="man:SubTable" minOccurs="0" maxOccurs="1"/>
        </xs:sequence>
        <xs:attribute name="name" type="xs:string" use="required">
          <xs:annotation>
            <xs:documentation>Table title (localizable).</xs:documentation>
          </xs:annotation>
        </xs:attribute>
        <xs:attribute name="topic" type="xs:string" use="optional">
          <xs:annotation>
            <xs:documentation>Topic title (localizable). A conceptual subsection under 
              section to group tables</xs:documentation>
          </xs:annotation>
        </xs:attribute>
        <xs:attribute name="level" use="optional" >
          <xs:annotation>
            <xs:documentation>Range 1 to 5. Used to control if this table will be 
              generated or not.  
              If the level of the table is less than or equal to the tracerpt system level,
              this table will be generated.  
              By setting system level in tracerpt by a command-line switch, only those 
              tables with proper level will be generated.  
              The table level and tracerpt system level are 1 by default.</xs:documentation>
          </xs:annotation>
          <xs:simpleType>
            <xs:restriction base="xs:integer">
              <xs:minInclusive value="1"/>
              <xs:maxInclusive value="5"/>
            </xs:restriction>
          </xs:simpleType>
        </xs:attribute>
        <xs:attribute name="key" type="xs:string" use="optional">
          <xs:annotation>
            <xs:documentation>Used to sort the tables.</xs:documentation>
          </xs:annotation>
        </xs:attribute>
        <xs:attribute name="note" type="xs:string" use="optional">
          <xs:annotation>
            <xs:documentation>Note text (localizable).</xs:documentation>
          </xs:annotation>
        </xs:attribute>
        <xs:attribute name="threshold" type="xs:positiveInteger" use="optional">
          <xs:annotation>
            <xs:documentation>The number of rows shown in the table when the report XML 
              file is rendered in Internet Explorer.  
              However, the real number of rows could be greater than the threshold value.
            </xs:documentation>
          </xs:annotation>
        </xs:attribute>
        <xs:attribute name="rowcount" type="xs:positiveInteger" use="optional">
          <xs:annotation>
            <xs:documentation>
              The number of rows in the report file and it can be used to control the report file size.
            </xs:documentation>
          </xs:annotation>
        </xs:attribute>
        <xs:attribute name="transaction" type="xs:boolean" use="optional">
          <xs:annotation>
            <xs:documentation>
              Boolean attribute to indicate if this table is about transaction statistics.  
              A transaction is defined as an activity in the same provider between an event 
              with opcode START/DC_START/DEQUEUE, called start event, and an event with 
              opcode STOP/DC_STOP/CHECKPOINT, called end event, with the same thread ID.  
              There are a few restrictions on a transactional table:
              There is no &lt;EqualJoin&gt; allowed for a transactional table.
              Fields &quot;sys:CPUPercent&quot; and &quot;sys:ResponseTime&quot; are only
              allowed in a transactional table.
              Maximum number of event field sources is still two 
              (see &lt;EventField&gt; for definition of event field source).
            </xs:documentation>
          </xs:annotation>
        </xs:attribute>
      </xs:complexType>
    </xs:element>
    <xs:complexType name="BaseEventField">
        <xs:attribute name="field" type="xs:string" use="required">
          <xs:annotation>
            <xs:documentation>
              The name of the field. The name of the property in the event payload.  
              Note that not only event payload property can be counted and reported, but 
              also the event header fields.  
              To differentiate the normal event properties from the event header fields, 
              a prefix &quot;sys:&quot; is used for those event header fields.
              In addition, there are several useful values to show in the table.
              They are not in the event payload or in the event header.
              They are calculated from the event header fields.
              The fields include CPU Utilization, Response Time, and Request Rate.
              A transaction is defined as an activity between an event with opcode start, 
              called start event, and an event with opcode end, called end event with the 
              same thread ID.
              Response time is that the time difference between the time stamp of a start 
              event and the time stamp of an end event.
              CPU utilization is that the CPU time consumed by the same thread in a 
              transaction divided by the response time.
              Request rate is that the number of events divided by the event trace duration.
              Note that users can specify task (optional attribute) for these three system 
              fields such that its calculations is on per-task per-provider basis.  Otherwise, 
              the three system fields are calculated on per-provider basis.
              System Fields:
              sys:Opcode - The opcode (type) of the event.
              sys:Task - The task of the event.
              sys:ProviderName - The name of the event provider.
              sys:TID -The Thread ID of the event.
              sys:PID - The Process ID of the event.
              sys:Timestamp - The time stamp of the event (in units of 100ns).
              sys:KCPU - The kernel-mode CPU time (in units of ms).
              sys:UCPU - The user-mode CPU time (in units of ms).
              sys:CPUPercent - The CPU utilization in units of percentage.
              sys:ResponseTime - The transaction response time (in unitd of ms).
              sys:RequestRate - The event rate (in units of request per second).
              sys:ActivityId - The event activity ID.
            </xs:documentation>
          </xs:annotation>
        </xs:attribute>
        <xs:attribute name="payloadGuid" type="man:GUIDType" use="required">
          <xs:annotation>
            <xs:documentation>A PLA-UID in the event header. The provider PLA-UID in XML event 
              manfiest and event PLA-UID in the WBEM MOF schema.</xs:documentation>
          </xs:annotation>
        </xs:attribute>
        <xs:attribute name="payloadId" type="xs:string" use="required">
          <xs:annotation>
            <xs:documentation>Refers to payloadId in the XML event manifest and type in the 
              WBEM MOF schema.  
              PayloadId plus version can identify an event payload within an event provider.
            </xs:documentation>
          </xs:annotation>
        </xs:attribute>
        <xs:attribute name="version" type="xs:string" use="optional">
          <xs:annotation>
            <xs:documentation>Event version.</xs:documentation>
          </xs:annotation>
        </xs:attribute>
      </xs:complexType>
 </xs:schema>

The following tables refer to elements that are specified above in the XSD as well as the semantic meaning of the attributes that are associated with those elements.

The Report element is the outermost element in the report schema and defines certain properties about the report. The Report element contains within it an optional StringTable section which contains the localization information; the Report element can also have either one Sections element or multiple Import elements as child elements.

  
 <Report>
    <Import>...</Import>
    <Sections>...</Sections>
    <StringTable>...</StringTable>
 </Report>

Attributes	Required/Optional	Description
name	Required	This is the name of the report that is being generated, and can be a localizable name.
version	Required	This is the version of the report that is being generated.
threshold	Optional	The number of rows to display in the table that is generated. If this value is not specified, then a default of 25 rows is used.

The Import element can be used to link to reports that might be defined in other XML files; this will not make duplicate definitions necessary.

Attributes	Required/Optional	Description
file	Required	The path to the XML file that includes the report definition to be included. This path can be an absolute or relative path.

The Sections element is used to indicate the beginning of a sequence of Section elements, where each Section refers to a logical entity or category that would be of interest in the report. There can be one or more Section elements within a Sections element:

  
 <Sections>
    <Section>...</Section>
 </Sections>

There are no attributes for this element; it is only used to indicate that one or more Section elements will follow.

Each Section element describes a category, and within this category, there can be a grouping of either performance counters or events. For example, all performance counters and events related to TCP/IP can be under a "Networking" Section element. The performance counters and events that are organized into a Section are described using EventTable and CounterTable elements, respectively. There can be one or more EventTable and CounterTable elements within a Section. The following is the layout of the Section part of the XML:

  
 <Section>
    <EventTable>...</EventTable>
    <CounterTable>...</CounterTable>
 </Section>

Attributes	Required/ Optional	Description
name	Required	The title of the section; this string can be localized.
key	Required	This is a non-negative number that is used to indicate in what position in the report the section will be displayed; the sections are displayed in ascending order.
note	Optional	This is an optional description of the section; the string can be localized.

Each Section can have one or more EventTable elements. Each EventTable element is used to define a table that will include event information, possibly from different event providers. The EventTable will consist of one or more columns, which will be used to display information about the event. In addition, it could be necessary to join two types of events from different event providers, much like a SQL join: this is done using the EqualJoin element. Finally, the EventTable can also have a SubTable, one that contains extra information that is not shown by default; the user can expand it to see more information.

The following is the XML definition of the EventTable:

  
 <EventTable>
    <Column>...</Column>
    <EqualJoin>...</EqualJoin>
    <SubTable>...</SubTable>
 </EventTable>

There can be one or more columns in the EventTable, but there can only be one EqualJoin and one SubTable; the elements need to be in the order specified above.

Attributes	Required/Optional	Description
name	Required	The title of the event table; this string can be localized.
topic	Required	This is the category of the events that are described in the table.
level	Optional	Level at which to generate this table; this value MUST be between 1 and 5. If not specified, then each table MUST be assigned a default level of 1. Tools that generate the report ought to only generate those tables that have a level less than or equal to what is specified to the tools.
key	Optional	This key is a non-negative number used to indicate in what order the event tables will be generated within the Section; they are displayed in ascending order, followed by tables with no key.
note	Optional	This is a description about the event table; it can be localized.
threshold	Optional	This value indicates the number of rows to display in the table by default. Tools that display the report ought to allow the user to page through the table if there are more rows in the table and the threshold is set below the total number of rows.
rowcount	Optional	This value indicates the total number of rows that ought to be in the table. This value is used to restrain the table size; if not specified, then all possible rows will be included.
transaction	Optional	A Boolean value which indicates whether the events in the table correspond to a transaction. Events can only correspond to a transaction if there are events of type "start" and type "stop" to indicate the beginning and ending of a transaction, respectively. If this is TRUE, then there cannot be an EqualJoin element.

The EventTable consists of one or more columns. Each column is used to display a property of the event; this can either be a part of the event header or the event payload that indicates the context in which the event was raised. There can be at most one field of an event that is displayed in a single column. The order that the columns are defined in the report is important because columns can be used to group by certain data fields when aggregation is performed on other data fields; this bucketizes the result of aggregation operations. For example, it is possible to group by process ID in one column, and then have a second following column which aggregates the event that is raised when a disk write takes place, with the event payload containing the number of bytes being written; in this way, the process which has been writing the most number of bytes to the disk can be determined. In order for this to happen correctly, the process ID column needs to be defined before the column that issues the disk write event. All the events that are defined in a table need to be from one event provider; the EqualJoin element is used to combine events from two event providers in a single table.

Each column contains one field from an event. The XML definition is:

  
 <Column>
    <EventField>...</EventField>
 </Column>

Attributes	Required/Optional	Description
name	Required	This is the name of the column; this can be localized and MUST be unique within the column.
align	Optional	This indicates how the values of the column will be aligned. The value of this attribute can either be "left" or "right". The default is "right".
format	Optional	This is an XSLT format number which indicates how numeric values will be displayed.
visible	Optional	This attribute indicates whether the tool displaying the report will show the column. The possible values are "true" or "false"; the default is "true".
summary	Optional	If this attribute is specified, the result either a "total" or "average" operation will be added to the footer of the table. The "total" operation sums the values of the rows in the column, while "average" will calculate the average of all the row values. This is only valid for columns that have numeric values.
groupby	Optional	This indicates that the values of the event field that is displayed in the row ought to be grouped by unique values. This is often specified when an aggregation is being performed in another column. Thus, there will be as many rows as there are unique values in the column. The possible values are "true" or "false"; when not specified, the default is "false".
sort	Optional	When multiple columns are specified, a column can serve as a primary sorter for the table or a secondary sorter. If it is designated as a primary sorter by setting the attribute to "primary", then when the table is created, the values in the column will be sorted in the manner specified in the "order" attribute. If it is designated as a secondary sorter by setting the attribute value to "secondary", then the primary column will be sorted first, and then this will be sorted in the manner specified in the "order" attribute, and within the constraints of the primary column; this is only valid when the column that is serving as the primary sorter has the groupby attribute specified.
order	Optional	When a column is being sorted, the values can either be sorted from smallest to largest or from largest to smallest. To sort in the format of the former, the attribute needs to be set to "ascending", and in the format of the latter, it needs to be set to "descending".
outtype	Optional	The format of the data values of the column when they are displayed to the user. See below for possible outTypes.

When the data in a column is displayed to the user, the values in the column can be formatted to a particular type; this is specified using the "outtype" attribute of the column definition. The following outtypes can be specified:

xs:string: XML string data type.
xs:dateTime: XML date time data type.
xs:byte: XML signed byte data type. (1 byte)
xs:unsignedByte: XML unsigned byte data type. (1 byte)
xs:short: XML signed short integer data type. (2 bytes)
xs:unsignedShort: XML unsigned short integer data type. (2 bytes)
xs:int: XML signed integer data type. (4 bytes)
xs:unsignedInt: XML unsigned integer data type. (4 bytes)
xs:long: XML signed long integer data type. (8 bytes)
xs:unsignedLong: XML unsigned long integer data type. (8 bytes)
xs:float: XML single-precision 32-bit floating point type.
xs:double: XML double-precision 64-bit floating point type.
xs:boolean: XML Boolean data type. (true, false, 1, 0)
xs:GUID: A PLA-UID.
xs:hexBinary: Contains a sequence of hexadecimal digits.
win:HexInt8: A hexadecimal number preceded by "0x".
win:HexInt16: A hexadecimal number preceded by "0x".
win:HexInt32: A hexadecimal number preceded by "0x".
win:HexInt64: A hexadecimal number preceded by "0x".
win:PID: Same as xs:int, represents a process ID.
win:TID: Same as xs:int, represents a thread ID.
win:Port: Same as xs:int, represents an IP address port.
win:IPv4: Dot separated IP address, valid for UInt32 or any string (in which case it is in the dotted string form).
win:IPv6: IPv6 string format for 128-bit binary or any string (in which case it is in string form).
win:SocketAddress: A 128-bit binary value that is displayed with the IP address followed by the port number; the port and IP address are separated by a dot.
win:CIMDateTime: Valid for any string, represents CIM date/time.
win:Xml: Valid for any string, represents any valid XML.
win:ErrorCode: Valid for win:UInt32 and represents a standard Windows error code.

When a column is defined, the rows in the column need to contain some value; the value to pull from the event is specified by the EventField element. The EventField element can refer to either a header field in an ETW event or a payload field. Moreover, an aggregation method can be performed on the data field, assuming that there is a column that has been defined before the column with the aggregate values that indicates how the aggregation ought to be grouped (specified using the "groupby" attribute of the column).

As mentioned above, the column row can either be a property from the header of an ETW event or a payload field. The ETW event header fields that can be used is specified in a table below; the field name needs to be prefixed with a "sys:".

The attributes of the EventField element are as follows:

Attributes	Required/Optional	Description
field	Required	The name of the field of the event. This field can either be a header field (see the table below), or the name of the payload field.
payloadGuid	Required	This is the PLA-UID that was logged with the event. This can either refer to the event PLA-UID or the PLA-UID of the ETW provider that logged the event. This PLA-UID is used in conjunction with the payloadId to use the right event in the column, as well as find the right field name since different event definitions might have the same payload field name.
payloadId	Required	This is the id of the event whose field indicated by the attribute field will be used to populate the column; this is used in conjunction with the value of the payloadGuid attribute.
version	Optional	This is the version of the event, and can be used in conjunction with the payloadGuid and payloadId attributes to find the event whose field specified by the attribute field will be used to populate the column. If this is not specified, then it is set to a default value of 0.
aggregate	Optional	This attribute indicates whether any operations ought to be performed on the field pointed to by the field attribute; this is used when there is another column that indicates how the results of the aggregation ought to be grouped. This attribute can take three values: total, average and rate.
note	Optional	A description for the field that is used to populate the rows of the column; this string can be localized.

Generally, the field attribute will point to a field in the payload of the event, which is uniquely defined by the values of the payloadGuid and payloadId attributes. However, a system field of that event can be used; only certain ETW event header fields can be used. They are as follows:

"Sys:Opcode": This is the opcode, or type, of the event.
"sys:ProviderName": This is the name of the ETW provider that logged the event.
"sys:TID": This is the ID of the thread from which the event was logged.
"sys:PID": This is the ID of the process from which the event was logged.
"sys:Timestamp": This is the time at which the event was logged, in units of 100 nanoseconds.
"sys:KCPU": This is the kernel CPU time of the thread, or the amount of time the process executed privileged instructions, at the time the event was logged, specified in units of milliseconds.
"sys:UCPU": This is the user CPU time of the thread, or the amount of time the process executed unprivileged instructions, at the time the event was logged, specified in units of milliseconds.
"sys:CPUPercent": This is not a standard ETW header field, but rather is valid only when the transaction attribute is set to TRUE for the EventTable. This is calculated by taking the sum of the KCPU and UCPU values of a thread and dividing that value by the difference between a "stop" event and "start" event type (denoting the ending and beginning of a transaction, respectively) on that same thread, and then normalizing to a percentage.
"sys:ResponseTime": This is not a standard ETW header field, but rather is valid only when the transaction attribute is set to TRUE for the EventTable. This is the time difference between a "stop" type event and a "start" type event (denoting the ending and beginning of a transaction, respectively) on the same thread.
"sys:RequestRate": This is not a standard ETW header field. This value is calculated by taking the total number of events and then dividing that value by the total duration of time when event collection was enabled.
"sys:AggregateCount": The total number of rows in a sub-table after an aggregation is performed

As specified in the attribute table above, there are three possible aggregation operations that can be performed: "total", "average" and "rate". These aggregation operations can be specified only when a previous column has a "groupby" attribute set to TRUE. Then, for each unique row in the column that has "groupby" set to TRUE, the aggregation operation will be performed for all events that fall under the bucket (indicated by one row in column with the groupby set to TRUE). If there are multiple columns with the "groupby" set to TRUE, then the grouping is processed from the first column definition moving to the next column definition and so on. The column that has "groupby" set to TRUE MUST NOT have an EventField element that has an "aggregate" attribute specified. The aggregation operations that can be performed are:

"Total": For each unique bucket that is defined by the columns where "groupby" is set to TRUE, the values of the field indicated by the "field" attribute are summed together. This is only valid for numeric fields.
"Average": For each unique bucket that is defined by the columns where "groupby" is set to TRUE, the values of the field indicated by the "field" attribute are averaged; the values will be summed and then divided by the number of events that fit that bucket. This is only valid for numeric fields.
"Rate": For each unique bucket that is defined by the columns where "groupby" is set to TRUE, the values of the field indicated by the "field" attribute are summed, and that result is then divided by the total duration of event collection. This is only valid for numeric fields.

In certain cases, it is necessary to combine the data from two event providers based on a common field, similar to the SQL Join operation. In such a case, the EqualJoin element needs to be specified under the EventTable element. The join can only take place on a single common field between two ETW event providers; a single provider is referenced by a EventJoinField element:

  
 <EqualJoin>
    <EventJoinField>...</EventJoinField>
    <EventJoinField>...</EventJoinField>
 </EqualJoin>

The EventJoinField element indicates what fields will be combined between the two event providers. For example, all values from the field "Field1" from event provider A can be matched to the values of the field "Field2" from event provider B. This, in turn, allows the EventTable table to contain information from two event providers instead of just one. The following describe the attributes of the EventJoinField element:

Attributes	Required/Optional	Description
field	Required	The name of the field on which the join operation will be performed.
payloadGuid	Required	The PLA-UID of the event provider which logs the event on which the join will be performed. This is used in conjunction with the value from the payloadId attribute to find the right event that defines the field indicated by the field attribute.
payloadId	Required	The Id of the event whose field indicated by the field attribute will be used in the join operation. This is used in addition to the payloadGuid attribute to find the event.
version	Optional	The version of the event whose field indicated by the field attribute will be used in the join operation. If this attribute is not specified, it is set to a default value of 0.

When displaying information to the user, often it is necessary to hide details, and only display this additional information to the user when required. This is often accomplished through the "expand" operation on a field. This report schema allows for defining sub-tables, with multiple columns, that can contain detailed information that SHOULD NOT be displayed to the user automatically; the table will display only when the user asks for more detailed information.

A Subtable can contain one or more columns; this is similar to the parent EventTable element, which can contain one or more columns. However, unlike the parent EventTable element, grouping and aggregation operations cannot be performed on the columns which belong to a subtable. The subtable, of which there can only be one under a given EventTable, is defined as follows:

  
 <SubTable>
    <Column>...</Column>
 </SubTable>

For each row that is defined in the parent EventTable, there will be an associated SubTable element. The user will "expand" the row to uncover the SubTable and its columns. The data in the SubTable will only correspond to the single row in the parent table that is being expanded.

Under the Section element, there can be either an EventTable element, which addresses events, or a CounterTable element, which address performance counter data. There can be one or more CounterTable elements under a Section element. The CounterTable defines which performance counters to include in the report, and which performance counters to exclude in the report. The following define the elements under the CounterTable element:

  
 <CounterTable>
    <Exclude>...</Exclude>
    <Include>...</Include>
 </CounterTable>

The following are the attributes for the CounterTable:

Attributes	Required /Optional	Description
name	Required	The title of the table; this string is localizable.
topic	Required	The category or topic of the table; this string is localizable.
object	Required	The name of the counter object which contains the counter.
level	Optional	Level at which to generate this table; acceptable values are from 1 to 5. If not specified, then each table is assigned a default level of 1. Tools that use this report ought to allow the user to specify a level (this is similar to "verbosity"). Only tables that have a level less than or equal to what the user specifies will be generated. If the user does not specify a level, then the default of 1 is used.
key	Optional	This is a non-negative value used to indicate in what order the event tables will be generated within the Section; they are displayed in ascending order, followed by tables with no keys.
note	Optional	An optional string which describes the table; this string is localizable.
threshold	Optional	This value indicates the number of rows to display in the table by default. Tools that display the report ought to allow the user to page through the table if there are more rows in the table and the threshold is set below the total number of rows.

When the CounterTable is generated, not all counters need to be included. Hence, the elements Include and Exclude allow specifying which particular counters will be included or excluded from the table, respectively.

The Exclude element specifies which counters belonging to the counter object specified in the object attribute of the CounterTable will not be included when the table is generated, or which columns will be excluded if a column name is specified.

Attributes	Required/Optional	Description
counter	Optional	This is the name pattern string of the counter that will be excluded. If the attribute has the letter "i", then the counter name matching will be case-insensitive. Characters that indicate pattern matching are as follows: "/" followed by a sequence of characters means that counter names with either begin or end with that sequence of characters will be excluded. "" represents zero or more characters. "\" represents an escape character, and is used to escape the above three characters. For example, setting this to "i/avg/" will exclude all counters beginning with "avg" by using a case-insensitive comparison.
column	Optional	This attribute indicates if certain columns will not be generated in the column table. The possible values are: "counter", "instance", "machine", "mean", "min" and "max".

Attributes

Required/Optional

Description

counter

Optional

This is the name pattern string of the counter that will be excluded. If the attribute has the letter "i", then the counter name matching will be case-insensitive. Characters that indicate pattern matching are as follows:

"/" followed by a sequence of characters means that counter names with either begin or end with that sequence of characters will be excluded.
"*" represents zero or more characters.
"\" represents an escape character, and is used to escape the above three characters.

For example, setting this to "i/avg*/" will exclude all counters beginning with "avg" by using a case-insensitive comparison.

column

Optional

This attribute indicates if certain columns will not be generated in the column table. The possible values are: "counter", "instance", "machine", "mean", "min" and "max".

The Include element specifies which counters belonging to the counter object specified in the object attribute of the CounterTable will be included when the table is generated.

Attributes	Required /Optional	Description
instance	Required	This is the name pattern string of the counter that will be included. If the attribute has the letter "i", then the counter name matching will be case-insensitive. Characters that indicate pattern matching are as follows: "/" followed by a sequence of characters means that counter names with either begin or end with that sequence of characters will be included. "" represents zero or more characters. "\" represents an escape character, and is used to escape the above three characters. For example, setting this to "i/avg/" will include counters beginning with "avg" by using a case-insensitive comparison.

Attributes

Required /Optional

Description

instance

Required

This is the name pattern string of the counter that will be included. If the attribute has the letter "i", then the counter name matching will be case-insensitive. Characters that indicate pattern matching are as follows:

"/" followed by a sequence of characters means that counter names with either begin or end with that sequence of characters will be included.

"*" represents zero or more characters.

"\" represents an escape character, and is used to escape the above three characters.

For example, setting this to "i/avg*/" will include counters beginning with "avg" by using a case-insensitive comparison.

When the CounterTable is generated, the table will have predefined columns that have not been explicitly excluded using the Exclude element. This will include the counter name, machine name, instance name, mean value ("mean"), maximum value ("max") and minimum value ("min"). The instance column will only display if the counter object that is specified in the object attribute of the CounterTable element actually has multiple instances. If there is only a single instance of that counter object, then the column SHOULD NOT be displayed.

All localizable strings in the manifest need to be placed in a StringTable section of the report. All localizable strings, such as table names, will be identified with a string ID; the StringTable is what will match the StringId to the correct localized string. The StringTable element can contain one or more String elements, with each String element corresponding to a localized string:

  
 <StringTable>
    <String>...</String>
 </StringTable>

The <String> element describes a single localized string; the localized string is matched by using the ID attribute:

Attributes	Required/Optional	Description
ID	Required	The ID of the localized string. This ID is specified for all fields that can contain a localized string, such as the table names. That ID is then matched with this ID in the string table, where the element value is the localized string to display.

2.2.3.3 Report Schema Formatting

Additional resources