ALTER EVENT SESSION (Transact-SQL)

  • 项目

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

主题链接图标 Transact-SQL 语法约定

语法

ALTER EVENT SESSION event_session_name
ON SERVER
{
    [ [ {  <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 } ]
}

参数

术语

定义

event_session_name

是现有事件会话的名称。

STATE = START | STOP

启动或停止事件会话。 此参数仅在 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 为事件对象。

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

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

为该事件指定可自定义的属性。 可自定义属性作为 column_type 'customizable ' 和 object_name = event_name 显示在 sys.dm_xe_object_columns 视图中。

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

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

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

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

  • action_name 是操作对象。

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

WHERE <predicate_expression>

指定用于确定是否应处理事件的谓词表达式。 如果 <predicate_expression> 是 true，则由会话的操作和目标对事件做进一步处理。 如果 <predicate_expression> 是 false，则在会话的操作和目标处理事件之前由会话删除该事件。 谓词表达式限制在 3000 个字符，这限制了字符串参数。

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 视图中定义的全局源。

DROP EVENT <event_specifier>

删除由 <event_specifier> 标识的事件。 <event_specifier> 在事件会话中必须有效。

ADD TARGET <event_target_specifier>

将由 <event_target_specifier> 标识的目标与事件会话关联。

[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]}

设置目标参数。 目标参数作为 column_type“customizable”和 object_name = target_name 显示在 sys.dm_xe_object_columns 视图中。

重要说明重要提示

如果使用环形缓冲区目标，我们建议您将 max_memory 目标参数设置为 2048 KB，以免在 XML 输出中可能发生数据截断。 有关何时使用不同的目标类型的详细信息，请参阅 SQL Server 扩展事件目标。

DROP TARGET <event_target_specifier>

删除由 <event_target_specifier> 标识的目标。 <event_target_specifier> 在事件会话中必须有效。

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

不允许事件丢失。 此选项可确保所有引发的事件都将得以保留。 使用此选项可强制所有激发事件的任务一直等到事件缓冲区中有可用空间时才执行。 这可能会在事件会话处于活动状态时引发可察觉到的性能问题。 在等待从缓冲区刷新事件时，用户连接可能中断。

MAX_DISPATCH_LATENCY = { seconds SECONDS | INFINITE }

指定在将事件调度至事件会话目标前这些事件在内存中缓冲的时间。 最小滞后时间值为 1 秒。 但是，可以使用 0 来指定 INFINITE 滞后时间。 默认情况下，此值设置为 30 秒。

seconds SECONDS

在开始将缓冲区刷新到目标前等待的时间（单位为秒）。 seconds 是一个整数。

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 之外，还创建了两个大小为 size 的缓冲区。 也就是说，用于事件缓冲的总内存为 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

启动时事件会话不启动。

注释

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

权限

要求具有 ALTER ANY EVENT SESSION 权限。

示例

下例启动一个事件会话，获取一些实时会话统计数据，然后将两个事件添加到现有会话中。

-- Start the event session
ALTER EVENT SESSION test_session
ON SERVER
STATE = start
GO
-- Obtain live session statistics 
SELECT * FROM sys.dm_xe_sessions
SELECT * FROM sys.dm_xe_session_events
GO

-- Add new events to the session
ALTER EVENT SESSION test_session ON SERVER
ADD EVENT sqlserver.database_transaction_begin,
ADD EVENT sqlserver.database_transaction_end
GO

请参阅

参考

CREATE EVENT SESSION (Transact-SQL)

DROP EVENT SESSION (Transact-SQL)

sys.server_event_sessions (Transact-SQL)

sys.dm_xe_objects (Transact-SQL)

sys.dm_xe_object_columns (Transact-SQL)

概念

SQL Server 扩展事件目标