2.2.4.2.2.4.3 event_session

The event_session element<55> is a complex type that represents a configuration of an XEvent session. This element is not used with Event or TraceFilter elements. The event_session element is defined in the following schema.

 <xs:element name="event_session" maxOccurs="unbounded" minOccurs="1">
    <xs:complexType>
       <xs:sequence>
          <xs:element name="templateCategory" minOccurs="0" maxOccurs="1" type="xs:string"/>
          <xs:element name="templateName" minOccurs="0" maxOccurs="1" type="xs:string" />
          <xs:element name="templateDescription" minOccurs="0" 
                      maxOccurs="1" type="xs:string" />
          <xs:element name="event" minOccurs="0" maxOccurs="unbounded" />
          <xs:element name="target" minOccurs="0" maxOccurs="unbounded"/>
       </xs:sequence>
          <xs:attribute name="name" type="xs:string" use="required"/>
          <xs:attribute name="maxMemory" type="xs:unsignedLong" use="optional" default="4" />
          <xs:attribute name="eventRetentionMode" type="retentionModes" 
                        use="optional" default="allowSingleEventLoss" />
          <xs:attribute name="dispatchLatency" type="xs:unsignedInt" 
                        use="optional" default="30"/>
          <xs:attribute name="maxEventSize" type="xs:unsignedInt" use="optional" default="0"/>
          <xs:attribute name="memoryPartitionMode" type="partitionModes" 
                        use="optional" default="none"/>
          <xs:attribute name="trackCausality" type="xs:boolean" 
                        use="optional" default="false"/>
    </xs:complexType>
 </xs:element>

The following tables describe the elements and attributes of the event_session complex type.

Element

Read-Only

Default value

Description

templateCategory

Category of a predefined XEvent session template.

templateName

Name of a predefined XEvent session template.

templateDescription

Description of a predefined XEvent session template.

event

List of XEvents to be activated within the session.

target

List of XEvent targets for the session.

Attribute

Read-Only

Default value

Description

name

[Required]

Name of the XEvent session.

maxMemory

4

Specifies the maximum amount of memory in MB to allocate to the session for event buffering.

eventRetentionMode

allowSingleEventLoss

Specifies the event retention mode to use for handling event loss.

dispatchLatency

30

Specifies the amount of time in seconds that events will be buffered in memory before being dispatched to event session targets.

maxEventSize

0

Specifies the maximum allowable size for events in MB.

The maxEventSize attribute SHOULD only be set to allow single events larger than maxMemory; setting it to less than maxMemory will cause the value to be ignored.

When maxEventSize is set, two buffers of size are created in addition to maxMemory.

This means that the total memory used for event buffering is maxMemory plus double the maxEventSize.

memoryPartitionMode

None

Specifies the location where event buffers are created.

trackCausality

False

Specifies whether causality is tracked. If enabled, causality allows related events on different threads to be correlated together.

The retentionModes simple type is defined as:

 <xs:simpleType name="retentionModes">
   <xs:restriction base="xs:string">
     <xs:enumeration value="allowSingleEventLoss"/>
     <xs:enumeration value="allowMultipleEventLoss"/>
     <xs:enumeration value="noEventLoss"/>
   </xs:restriction>
 </xs:simpleType>

The following table describes the supported retention modes.

Mode

Description

allowSingleEventLoss

An event can be lost from the session. A single event is dropped only when all the event buffers are full.

Losing a single event when event buffers are full allows for acceptable SQL Server performance characteristics, while minimizing the loss of data in the processed event stream.

allowMultipleEventLoss

Full event buffers that contain multiple events can be lost from the session.

The number of events lost is dependent upon the memory size allocated to the session, the partitioning of the memory, and the size of the events in the buffer. This option minimizes performance impact on the server when event buffers are quickly filled, but large numbers of events can be lost from the session.

noEventLoss

No event loss is allowed. This option ensures that all events raised will be retained.

Using this option forces all tasks that fire events to wait until space is available in an event buffer.

This causes detectable performance issues while the event session is active.

The partitionModes simple type is defined as:

 <xs:simpleType name="partitionModes">
     <xs:restriction base="xs:string">
        <xs:enumeration value="none"/>
        <xs:enumeration value="perNode"/>
        <xs:enumeration value="perCpu"/>
     </xs:restriction>
 </xs:simpleType>

The following table describes the supported memory partitioning modes.

Mode

Description

none

A single set of buffers is created within the process

perNode

A set of buffers is created for each non-uniform memory access (NUMA) node. For more information about NUMA nodes, see [MSDN-NUMA].

perCpu

A set of buffers is created for each CPU.