ALTER EVENT SESSION （Transact-SQL）

适用于：SQL ServerAzure SQL 托管实例

启动或停止事件会话，或更改事件会话配置。

Transact-SQL 语法约定

语法

ALTER EVENT SESSION event_session_name
ON { SERVER | DATABASE }
{
    [ [ {  <add_drop_event> [ , ...n ] }
       | { <add_drop_event_target> [ , ...n ] } ]
    [ WITH ( <event_session_options> [ , ...n ] ) ]
    ]
    | [ STATE = { START | STOP } ]
}

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

<event_specifier> ::=
{
[event_module_guid].event_package_name.event_name
}
<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'
}

<add_drop_event_target>::=
{
    ADD TARGET <event_target_specifier>
        [ ( SET { target_parameter_name = <value> [ , ...n ] } ) ]
    | DROP TARGET <event_target_specifier>
}

<event_target_specifier>::=
{
    [event_module_guid].event_package_name.target_name
}

<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

现有事件会话的名称。

STATE = START |停

启动或停止事件会话。 STATE必须自行指定自变量。 它不能与同一语句中的其他任何参数组合在一起 ALTER EVENT SESSION 。

ADD EVENT <event_specifier>

标识要与事件会话关联的事件。 < > event_specifier采用 [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 字符串。 不为谓词比较函数执行隐式字符串类型转换。 传递意外类型的值会导致错误。

DROP EVENT <event_specifier>

标识要从事件会话中删除的事件。 事件说明符采用 [event_module_guid] 的形式。event_package_name。event_name，其中：

• event_module_guid 为包含该事件的模块的 GUID。

• event_package_name 为包含操作对象的包。

• event_name 为事件对象。

  < > event_specifier必须标识以前添加到事件会话的事件。

添加 TARGET <event_target_specifier>

标识要与事件会话关联的目标。 事件目标说明符采用 [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';

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

DROP TARGET <event_target_specifier>

标识要从事件会话中删除的目标。 事件目标说明符采用 [event_module_guid] 的形式。event_package_name。target_name，其中：

• event_module_guid 为包含该事件的模块的 GUID。
• event_package_name 为包含操作对象的包。
• target_name 是目标的名称。

事件目标说明符必须标识以前添加到事件会话的目标。

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 数据库和 Azure SQL 托管实例（SQL Server 2025 或 Always-up-to-date更新策略）中的事件文件目标， NO_EVENT_LOSS 从 2024 年 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 数据库和 Azure SQL 托管实例时将其删除为受支持的 EVENT_RETENTION_MODE 参数。 避免在新开发工作中使用此功能，并计划修改当前使用此功能的应用程序。

MAX_DISPATCH_LATENCY = { seconds SECONDS |INFINITE }

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

• seconds 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 }

指定在数据库引擎启动时是否自动启动此事件会话。

• ON

  事件会话在启动时启动。

• OFF

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

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

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

• 无限

  导致事件会话在启动后无限期运行，直到使用 ALTER EVENT SESSION ... STATE = STOP 语句停止为止。

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

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

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

注解

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

ADD不能在同一语句中使用参数和DROP参数。

权限

SQL Server 和 Azure SQL 托管实例需要 ALTER ANY EVENT SESSION 权限。

Azure SQL 数据库需要 ALTER ANY DATABASE EVENT SESSION 数据库中的权限。

示例

答： 启动和停止事件会话

若要将此示例用于数据库事件会话，请替换为 ON SERVERON DATABASE。

ALTER EVENT SESSION test_session ON SERVER STATE = START;
ALTER EVENT SESSION test_session ON SERVER STATE = STOP;

B. 将新事件添加到现有会话

若要将此示例用于数据库事件会话，请替换为 ON SERVERON DATABASE。

ALTER EVENT SESSION test_session ON SERVER
ADD EVENT sqlserver.database_transaction_begin,
ADD EVENT sqlserver.database_transaction_end;

C. 查看会话统计信息

若要将此示例与数据库事件会话一起使用，请替换为sys.dm_xe_sessionssys.dm_xe_database_sessions和sys.dm_xe_session_events替换为 sys.dm_xe_database_session_events。

SELECT *
FROM sys.dm_xe_sessions
WHERE name = 'test_session';

SELECT se.*
FROM sys.dm_xe_session_events AS se
WHERE EXISTS (SELECT 1
              FROM sys.dm_xe_sessions AS s
              WHERE s.address = se.event_session_address
                    AND s.name = 'test_session');

相关内容

• CREATE EVENT SESSION （Transact-SQL）
• DROP EVENT SESSION （Transact-SQL）
• SQL Server 扩展事件目标
• sys.server_event_sessions（Transact-SQL）
• sys.dm_xe_objects（Transact-SQL）
• sys.dm_xe_object_columns（Transact-SQL）