CREATE EVENT SESSION （Transact-SQL）

适用于：SQL ServerAzure SQL 数据库Azure SQL 托管实例Microsoft Fabric 预览版中的 SQL 数据库

创建一个扩展事件会话，用于标识要收集的事件、事件会话目标和事件会话选项。

Transact-SQL 语法约定

语法

CREATE EVENT SESSION event_session_name
ON { SERVER | DATABASE }
{
    <event_definition> [ , ...n ]
    [ <event_target_definition> [ , ...n ] ]
    [ WITH ( <event_session_options> [ , ...n ] ) ]
}
;

<event_definition>::=
{
    ADD EVENT [event_module_guid].event_package_name.event_name
         [ ( {
                 [ SET { event_customizable_attribute = <value> [ , ...n ] } ]
                 [ ACTION ( { [event_module_guid].event_package_name.action_name [ , ...n ] } ) ]
                 [ WHERE <predicate_expression> ]
        } ) ]
}

<predicate_expression> ::=
{
    [ NOT ] <predicate_factor> | { ( <predicate_expression> ) }
    [ { AND | OR } [ NOT ] { <predicate_factor> | ( <predicate_expression> ) } ]
    [ , ...n ]
}

<predicate_factor>::=
{
    <predicate_leaf> | ( <predicate_expression> )
}

<predicate_leaf>::=
{
      <predicate_source_declaration> { = | < > | != | > | >= | < | <= } <value>
    | [event_module_guid].event_package_name.predicate_compare_name ( <predicate_source_declaration> , <value> )
}

<predicate_source_declaration>::=
{
    event_field_name | ( [event_module_guid].event_package_name.predicate_source_name )
}

<value>::=
{
    number | 'string'
}

<event_target_definition>::=
{
    ADD TARGET [event_module_guid].event_package_name.target_name
        [ ( SET { target_parameter_name = <value> [ , ...n ] } ) ]
}

<event_session_options>::=
{
    [       MAX_MEMORY = size [ KB | MB ] ]
    [ [ , ] EVENT_RETENTION_MODE = { ALLOW_SINGLE_EVENT_LOSS | ALLOW_MULTIPLE_EVENT_LOSS | NO_EVENT_LOSS } ]
    [ [ , ] MAX_DISPATCH_LATENCY = { seconds SECONDS | INFINITE } ]
    [ [ , ] MAX_EVENT_SIZE = size [ KB | MB ] ]
    [ [ , ] MEMORY_PARTITION_MODE = { NONE | PER_NODE | PER_CPU } ]
    [ [ , ] TRACK_CAUSALITY = { ON | OFF } ]
    [ [ , ] STARTUP_STATE = { ON | OFF } ]
    [ [ , ] MAX_DURATION = { <time duration> { SECONDS | MINUTES | HOURS | DAYS } | UNLIMITED } ]
}

参数

event_session_name

事件会话的用户定义名称。 event_session_name 为字母数字，最多可以包含 128 个字符，在 SQL Server 实例中必须唯一，并且必须符合 数据库标识符的规则。

ON { SERVER |DATABASE }

确定事件会话是否位于服务器或数据库的上下文中。

Microsoft Fabric 预览版中的 Azure SQL 数据库和 SQL 数据库需要 DATABASE。

ADD EVENT [event_module_guid]。event_package_name。event_name

要与事件会话关联的事件，其中：

• event_module_guid 为包含该事件的模块的 GUID。
• event_package_name 是包含事件的包。
• event_name 是事件名称。

可以通过执行以下查询来找到可用事件：

SELECT o.name AS event_name,
       o.description AS event_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'event'
ORDER BY event_name ASC;

SET { event_customizable_attribute = <value> [ ,...n ] }

事件的可自定义属性。

可以通过执行以下查询找到给定事件的可自定义属性：

SELECT object_name,
       name AS column_name,
       type_name,
       column_value,
       description
FROM sys.dm_xe_object_columns
WHERE object_name = 'event-name-placeholder'
      AND column_type = 'customizable'
ORDER BY column_name ASC;

ACTION （ { [event_module_guid]。event_package_name。action_name [ ,...n ] }）

要与事件关联的作，其中：

• event_module_guid 是包含作的模块的 GUID。
• event_package_name 是包含作的包。
• action_name 是作的名称。

可以通过执行以下查询来找到可用作：

SELECT o.name AS action_name,
       o.description AS action_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'action'
ORDER BY action_name ASC;

WHERE <predicate_expression>

指定用于确定是否应处理事件的谓词表达式。 如果 <predicate_expression> 为 true，则由会话的操作和目标对事件做进一步处理。 如果 <predicate_expression> 为 false，则会删除该事件，避免执行其他操作和目标处理。 每个谓词表达式限制为 3,000 个字符。

event_field_name

标识谓词源的事件字段的名称。

可以通过执行以下查询找到事件的字段：

SELECT oc.name AS field_name,
       oc.type_name AS field_type,
       oc.description AS field_description
FROM sys.dm_xe_objects AS o
INNER JOIN sys.dm_xe_packages AS p
ON o.package_guid = p.guid
INNER JOIN sys.dm_xe_object_columns AS oc
ON o.name = oc.object_name
   AND
   o.package_guid = oc.object_package_guid
WHERE o.object_type = 'event'
      AND
      o.name = 'event-name-placeholder'
      AND
      oc.column_type = 'data'
ORDER BY field_name ASC;

[event_module_guid]。event_package_name。predicate_source_name

全局谓词源的名称，其中：

• event_module_guid 为包含该事件的模块的 GUID。
• event_package_name 是包含谓词源对象的包。
• predicate_source_name 是谓词源的名称。

可以通过执行以下查询来找到谓词源：

SELECT o.name AS predicate_source_name,
       o.description AS predicate_source_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'pred_source'
ORDER BY predicate_source ASC;

[event_module_guid].event_package_name.predicate_compare_name

谓词比较器对象的名称，其中：

• event_module_guid 为包含该事件的模块的 GUID。
• event_package_name 是包含谓词比较器对象的包。
• predicate_compare_name 是谓词比较器名称。

可以通过执行以下查询来找到谓词比较器：

SELECT o.name AS predicate_comparator_name,
       o.description AS predicate_comparator_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'pred_compare'
ORDER BY predicate_comparator ASC;

数字

任何可表示为 64 位整数的数字类型。

“string”

谓词比较器所需的 ANSI 或 Unicode 字符串。 不为谓词比较函数执行隐式字符串类型转换。 传递意外类型的值会导致错误。

ADD TARGET [event_module_guid].event_package_name.target_name

表示要与事件会话关联的目标，其中：

• event_module_guid 是包含目标的模块的 GUID。
• event_package_name 是包含目标的包。
• target_name 是目标名称。

可以通过执行以下查询来找到可用目标：

SELECT o.name AS target_name,
       o.description AS target_description,
       o.capabilities_desc,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'target'
ORDER BY target_name ASC;

事件会话可以有零个、一个或多个 目标。 添加到事件会话的所有目标必须不同。 例如，不能将第二 event_file 个目标添加到已具有 event_file 目标的会话。

有关详细信息，包括常用目标的用法示例，请参阅 扩展事件目标。

SET { target_parameter_name = <value> [ ， ...n ] }

设置目标参数。

若要查看所有目标参数及其说明，请执行以下查询，替换为 target-name-placeholder 目标名称，例如 event_file， ring_buffer， histogram等等：

SELECT name AS target_parameter_name,
       column_value AS default_value,
       description
FROM sys.dm_xe_object_columns
WHERE column_type = 'customizable'
      AND object_name = 'target-name-placeholder';

有关目标类型的详细信息，请参阅 扩展事件目标。

WITH （ <event_session_options> [ ,...n ]

指定要用于事件会话的选项。

MAX_MEMORY = 大小 [ KB |MB ]

指定要分配给会话用来缓冲事件的最大内存量。 默认为 4 MB。size 为整数，并且其值可以以千字节 (KB) 或兆字节 (MB) 表示。 最大金额不能超过 2 GB（2,048 MB）。 但是，不建议在 GB 范围内使用内存值。

EVENT_RETENTION_MODE = { ALLOW_SINGLE_EVENT_LOSS |ALLOW_MULTIPLE_EVENT_LOSS |NO_EVENT_LOSS }

指定要用于处理事件丢失的事件保留模式。

• ALLOW_SINGLE_EVENT_LOSS

  事件可能会从会话中丢失。 只有在所有事件缓冲区均已满时才删除单个事件。 当事件缓冲区已满时丢失单个事件可最大程度地降低性能影响，同时最大程度地减少已处理事件流中的数据丢失。

• ALLOW_MULTIPLE_EVENT_LOSS

  包含多个事件的已满事件缓冲区可能会从会话中丢失。 丢失事件的数目取决于分配给会话的内存大小、内存的分区情况以及缓冲区中事件的大小。 此选项通常避免在快速填充事件缓冲区时对服务器造成性能影响，但大量事件可能会从会话中丢失。

• NO_EVENT_LOSS

  不允许事件丢失。 此选项可确保保留所有引发的事件。 使用此选项可强制所有激发事件的任务一直等到事件缓冲区中有可用空间时才执行。 使用NO_EVENT_LOSS可能会导致事件会话处于活动状态时出现可检测的性能问题。 等待从缓冲区刷新事件时，用户会话和查询可能会停止。

  注意

  对于 Azure SQL 数据库中的事件文件目标、Microsoft Fabric 预览版中的 SQL 数据库和 Azure SQL 托管实例（使用 SQL Server 2025 或 Always-up-to-date更新策略），从 2024 NO_EVENT_LOSS 年 6 月起的行为相同 ALLOW_SINGLE_EVENT_LOSS。 如果指定 NO_EVENT_LOSS，则返回消息 ID 为 25665、严重性 10 和消息 This target doesn't support the NO_EVENT_LOSS event retention mode. The ALLOW_SINGLE_EVENT_LOSS retention mode is used instead. 的警告，并创建会话。

  此更改可避免连接超时、故障转移延迟和其他问题，当与 Azure Blob 存储中的事件文件目标一起使用时 NO_EVENT_LOSS 降低数据库可用性。

  NO_EVENT_LOSS 计划在将来更新 Azure SQL 数据库、Microsoft Fabric 预览版中的 SQL 数据库和 Azure SQL 托管实例时将其删除为受支持的 EVENT_RETENTION_MODE 参数。 请避免在新的开发工作中使用该功能，并着手修改当前还在使用该功能的应用程序。

MAX_DISPATCH_LATENCY = { seconds SECONDS |INFINITE }

指定在将事件调度至事件会话目标前这些事件在内存中缓冲的时间。 默认情况下，此值设置为 30 秒。

• 秒SECONDS

  在开始将缓冲区刷新到目标前等待的时间（单位为秒）。 seconds 是一个整数。 最小滞后时间值为 1 秒。 但是，可以使用 0 来指定 INFINITE 滞后时间。

• 无限

  仅在缓冲区已满或事件会话关闭时才将缓冲区刷新到目标。

MAX_EVENT_SIZE = 大小 [ KB |MB ]

指定允许的最大事件大小。 应仅将MAX_EVENT_SIZE设置为允许大于 MAX_MEMORY; 的单个事件;将其设置为小于MAX_MEMORY会引发错误。 size 是整数，并且其值可以以千字节 (KB) 或兆字节 (MB) 表示。 如果以千字节为单位指定 size，则允许的最小大小为 64 KB。 设置MAX_EVENT_SIZE时，除了MAX_MEMORY之外，还会创建两个大小缓冲区，用于事件缓冲的总内存MAX_MEMORY + 2 * MAX_EVENT_SIZE。

MEMORY_PARTITION_MODE = { NONE |PER_NODE |PER_CPU }

指定事件缓冲区的相关性。 除了产生更多缓冲区和更高的内存消耗以外的 NONE 选项，但可以避免争用并提高较大计算机上的性能。

• 没有

  在数据库引擎实例中创建一组缓冲区。

• PER_NODE

  为每个 NUMA 节点创建一组缓冲区。

• PER_CPU

  为每个 CPU 创建一组缓冲区。

TRACK_CAUSALITY = { ON |OFF }

指定是否跟踪因果关系。 如果已启用，因果关系将允许将不同服务器连接上的相关事件关联在一起。

STARTUP_STATE = { ON |OFF }

指定在 SQL Server 启动时是否自动启动此事件会话。

• ON

  事件会话在启动时启动。

• OFF

  事件会话未在启动时启动。

MAX_DURATION = { 持续时间 { SECONDS |分钟 |HOURS |DAYS } |UNLIMITED }

适用于：SQL Server 2025 （17.x） 预览版

• 无限

  创建一个事件会话，该会话在启动后无限期运行，直到使用 ALTER EVENT SESSION ... STATE = STOP 语句停止为止。 如果未 MAX_DURATION 指定，则为默认值。

• 持续时间 SECONDS |分钟 |HOURS |日

  创建在会话启动后指定时间过后自动停止的事件会话。 支持的最大持续时间为 2,147,483 秒，或 35,792 分钟，或 596 小时或 24 天。

有关详细信息，请参阅 时间绑定事件会话。

注解

有关事件会话参数的详细信息，请参阅 扩展事件会话。

逻辑运算符的优先顺序是 NOT（最高），然后是 AND，最后是 OR。

权限

SQL Server 和 Azure SQL 托管实例需要 CREATE ANY EVENT SESSION （在 SQL Server 2022 中引入）或 ALTER ANY EVENT SESSION 权限。

Microsoft Fabric 预览版中的 Azure SQL 数据库和 SQL 数据库需要 CREATE ANY DATABASE EVENT SESSION 数据库中的权限。

示例

答： SQL Server 和 Azure SQL 托管实例示例

以下示例说明如何创建一个名为 test_session 的事件会话。 此示例添加两个事件并使用 event_file 目标，将每个文件的大小限制为 256 MB，并将保留的文件数限制为 10。

IF EXISTS (SELECT 1
           FROM sys.server_event_sessions
           WHERE name = 'test_session')
    DROP EVENT SESSION test_session ON SERVER;

CREATE EVENT SESSION test_session ON SERVER
ADD EVENT sqlserver.rpc_starting,
ADD EVENT sqlserver.sql_batch_starting,
ADD EVENT sqlserver.error_reported
ADD TARGET package0.event_file
    (
    SET filename = N'C:\xe\test_session.xel',
        max_file_size = 256,
        max_rollover_files = 10
    )
WITH (MAX_MEMORY = 4 MB);

B. Azure SQL 数据库示例

有关示例演练，请查看在 Azure 存储中创建具有event_file目标的事件会话 ，并使用 内存中的ring_buffer目标创建事件会话。

Azure SQL 数据库和 SQL 托管实例的代码示例可能有所不同

为 SQL Server 编写的一些 Transact-SQL 代码示例需要进行少量更改才能在 Azure SQL 数据库或 Fabric 中的 SQL 数据库中运行。 此类代码示例的其中一个类别涉及目录视图，其名称前缀因数据库引擎类型而异：

• server_ - SQL Server 和 Azure SQL 托管实例的前缀
• database_ - Azure SQL 数据库、Fabric 中的 SQL 数据库和 SQL 托管实例的前缀

Fabric 中的 Azure SQL 数据库和 SQL 数据库仅支持数据库范围内的事件会话。 SQL Server Management Studio （SSMS） 支持 Azure SQL 数据库的数据库范围事件会话：在对象资源管理器中的每个数据库下显示包含数据库范围的会话的扩展事件节点。

Azure SQL 托管实例既支持数据库范围的会话，也支持服务器范围的会话。 SSMS 完全支持 SQL 托管实例的服务器范围的会话：包含所有服务器范围的会话的“扩展事件”节点显示在对象资源管理器中每个托管实例的“管理”文件夹下。

为便于说明，下表列出并比较了目录视图的两个子集。 这些子集具有不同的名称前缀，因为它们支持不同的数据库引擎类型。

相关内容

• 在 Azure 存储中创建具有event_file目标的事件会话
• 扩展事件目标
• sys.server_event_sessions（Transact-SQL）
• sys.dm_xe_objects（Transact-SQL）
• sys.dm_xe_object_columns（Transact-SQL）
• ALTER EVENT SESSION （Transact-SQL）
• DROP EVENT SESSION （Transact-SQL）