Using Bitmasks in Extended Events Predicates

There are several events that return fields that can contain multiple values for a single event. For example, the error_reported event includes a destination field that identifies the list of all the destinations for the error that was returned. To support fields that contain multiple values, Extended Events uses maps that are returned as bitmasks. When you create predicates for bitmask fields, Extended Events requires the use of special predicate comparators.

How to use bitmasks in a predicate

Following are some examples of how to use the error_destination map:

Assume the following map_values:

2 - USER
4 - ERRLOG
8 - EVENTLOG

-- Collect events where USER is the only destination for the error

ADD EVENT sqlserver.error_reported (WHERE destination = 2)

 

-- Collect events where USER and ERRLOG are both the only destinations for the error

ADD EVENT sqlserver.error_reported (WHERE package0.is_all_on_uint64(destination, 6))

 

-- Collect events where USER and EVENTLOG are included in the destinations for the error

ADD EVENT sqlserver.error_reported (WHERE package0.is_any_on_uint64(destination, 10))

You can identify the list of events that contain bitmask fields with the following query:

SELECT object_name [event_name], oc.name [bitmask_field_name], oc.type_name [map_name], oc.description [bitmask_field_desc], bitmasks.description [bitmask_desc]

FROM sys.dm_xe_object_columns oc INNER JOIN

       (SELECT * FROM sys.dm_xe_objects

WHERE object_type = 'map' and capabilities & 256 = 256) bitmasks

              ON oc.type_name = bitmasks.name

ORDER BY event_name, bitmask_field_name