2.2.4.2.2.4.3 event_session

Article
02/16/2023

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

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.

Share via

2.2.4.2.2.4.3 event_session

Additional resources