CREATE EVENT SESSION (Transact-SQL)

适用于： SQL Server Azure SQL 数据库 Azure 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 } ]
}

参数

event_session_name

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

ADD EVENT [ event_module_guid ].event_package_name.event_name

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

• event_module_guid 为包含该事件的模块的 GUID。
• event_package_name 为包含操作对象的包。
• event_name 为事件对象。

事件在 sys.dm_xe_objects 视图中显示为 object_type 'event'。

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

允许设置事件的可自定义属性。 可自定义属性在 sys.dm_xe_object_columns 视图中显示为 column_type 'customizable ' 以及 object_name = event_name。

ACTION ( { [event_module_guid].event_package_name.action_name [ ,...n] })

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

• event_module_guid 为包含该事件的模块的 GUID。
• event_package_name 为包含操作对象的包。
• action_name 为操作对象。

操作在 sys.dm_xe_objects 视图中显示为 object_type 'action'。

WHERE <predicate_expression>

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

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

[event_module_guid].event_package_name.predicate_source_name：全局谓词源的名称，其中：

• event_module_guid 为包含该事件的模块的 GUID。
• event_package_name 为包含谓词对象的包。
• predicate_source_name 是作为 object_type 'pred_source' 在 sys.dm_xe_objects 视图中定义的。

[event_module_guid].event_package_name.predicate_compare_name：与事件关联的谓词对象的名称，其中：

• event_module_guid 为包含该事件的模块的 GUID。
• event_package_name 为包含谓词对象的包。
• predicate_compare_name 是作为 object_type 'pred_compare' 在 sys.dm_xe_objects 视图中定义的全局源。

number：任意数值类型，包括 decimal。 局限性在于缺少可用物理内存，或数值过大而无法用 64 位整数表示。

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

ADD TARGET [event_module_guid].event_package_name.target_name

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

• event_module_guid 为包含该事件的模块的 GUID。
• event_package_name 为包含操作对象的包。
• target_name 为目标。 目标作为 object_type 'target' 显示在 sys.dm_xe_objects 视图中。

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

设置目标参数。

若要查看所有目标参数及其说明，请执行以下查询，将 target-name 占位符替换为目标名称，例如 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';

重要

如果使用环形缓冲区目标，建议将目标参数（不同于MAX_MEMORY会话参数）设置为 MAX_MEMORY 1024 KB（KB）或更少，以帮助避免可能的数据截断 XML 输出。

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

WITH ( <event_session_options> [ ,...n] )

指定要与事件会话一起使用的选项。

MAX_MEMORY =size [ 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：一个事件可能会从会话中丢失。 只有在所有事件缓冲区均已满时才删除单个事件。 通过在事件缓冲区已满时丢失单个事件，SQL Server 可实现足以满足要求的性能特征，同时还可使处理的事件流中的数据丢失降到最低。

ALLOW_MULTIPLE_EVENT_LOSS：包含多个事件的已满事件缓冲区可能会从会话中丢失。 丢失事件的数目取决于分配给会话的内存大小、内存的分区情况以及缓冲区中事件的大小。 在事件缓冲区迅速达到已满状态时，该选项可将对服务器性能的影响降至最低，但可能会有大量的事件从会话中丢失。

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

注意

对于从 2024 年 6 月起，Azure SQL 数据库和Azure SQL 托管实例中事件文件目标与始终最新的更新策略相同，NO_EVENT_LOSS的行为与ALLOW_SINGLE_EVENT_LOSS相同。 如果指定NO_EVENT_LOSS，则消息 ID 为 25665、严重性为 10 且此目标不支持NO_EVENT_LOSS事件保留模式的消息 。改用ALLOW_SINGLE_EVENT_LOSS保留模式。 返回并创建会话。

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

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

MAX_DISPATCH_LATENCY = { seconds SECONDS | INFINITE }

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

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

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

注意

MAX_DISPATCH_LATENCY = 0 SECONDS 等效于 MAX_DISPATCH_LATENCY = INFINITE。

MAX_EVENT_SIZE =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：在 SQL Server 实例中创建一组缓冲区。

PER_NODE：为每个 Numa 节点创建一组缓冲区。

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

TRACK_CAUSALITY = { ON | OFF }

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

STARTUP_STATE = { ON | OFF }

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

注意

如果 STARTUP_STATE = ON，则事件会话将只在 SQL Server 停止并重新启动的情况下才启动。

ON：事件会话随之启动。

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

注解

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

权限

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

在 SQL 数据库上，需要在数据库中拥有 ALTER ANY DATABASE EVENT SESSION 权限。

提示

SQL Server 2022 为扩展事件引入了一些更精细的新权限，有关详细信息，请参阅 博客：SQL Server 2022 和 Azure SQL 的新粒度权限以提高对 PoLP 的遵守。

示例

SQL Server 示例

以下示例说明如何创建一个名为 test_session 的事件会话。 此示例添加了两个事件并使用 Windows 事件跟踪目标。

IF EXISTS(SELECT * FROM sys.server_event_sessions WHERE name='test_session')
    DROP EVENT session test_session ON SERVER;
GO
CREATE EVENT SESSION test_session
ON SERVER
    ADD EVENT sqlos.async_io_requested,
    ADD EVENT sqlserver.lock_acquired
    ADD TARGET package0.etw_classic_sync_target
        (SET default_etw_session_logfile_path = N'C:\demo\traces\sqletw.etl' )
    WITH (MAX_MEMORY=4MB, MAX_EVENT_SIZE=4MB);
GO

Azure SQL 示例

在 Azure SQL 托管实例或 Azure SQL 数据库中，将 .xel 文件存储在 Azure Blob 存储中。 可以使用 sys.fn_xe_file_target_read_file 从你自己创建的扩展事件会话进行读取，并存储在 Azure Blob 存储中。 有关示例演练，请参阅 Azure SQL 数据库和 Azure SQL 托管实例中扩展事件的事件文件目标代码。

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

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

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

Azure SQL 数据库仅支持数据库范围的事件会话。 SQL Server Management Studio (SSMS) 完全支持 Azure SQL 数据库的数据库范围事件会话：包含数据库范围会话的“扩展事件”节点显示在对象资源管理器中的每个数据库下。

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

注意

对于托管实例，建议使用服务器范围的会话。 数据库范围的会话不显示在 Azure SQL 托管实例的 SSMS 中的对象资源管理器中。 使用托管实例时，只能使用 Transact-SQL 查询和管理数据库范围的会话。

为便于说明，下表列出并比较了目录视图的两个子集。 为简洁起见，将子集限制为也包含字符串 _event 的视图名称。 这些子集具有不同的名称前缀，因为它们支持不同的数据库引擎类型。

SQL Server 和 Azure SQL 托管实例中的名称	Azure SQL 数据库和 Azure SQL 托管实例中的名称
server_event_notifications server_event_session_actions server_event_session_events server_event_session_fields server_event_session_targets server_event_sessions server_events server_trigger_events	database_event_session_actions database_event_session_events database_event_session_fields database_event_session_targets database_event_sessions

上表中的两个列表精确到 2022 年 3 月。 若要获得最新列表，请运行以下 Transact-SQL SELECT 语句：

SELECT name
    FROM sys.all_objects
    WHERE
        (name LIKE 'database[_]%' OR
         name LIKE 'server[_]%' )
        AND name LIKE '%[_]event%'
        AND type = 'V'
        AND SCHEMA_NAME(schema_id) = 'sys'
    ORDER BY name;

另请参阅

• 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)