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 是事件物件。 事件會出現在 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，則此事件會先由工作階段卸除，再由工作階段的動作和目標進行處理。述詞運算式限制為 3000 個字元，這會限制字串引數。
event_field_name	為識別述詞來源之事件欄位的名稱。
[event_module_guid].event_package_name.predicate_source_name	為全域述詞來源的名稱，其中： event_module_guid 是包含此事件之模組的 GUID。 event_package_name 是包含此述詞物件的封裝。 predicate_source_name 會在 sys.dm_xe_objects 檢視表中定義為 object_type 'pred_source'。
[event_module_guid].event_package_name.predicate_compare_name	為要與事件產生關聯的述詞物件名稱，其中： event_module_guid 是包含此事件之模組的 GUID。 event_package_name 是包含此述詞物件的封裝。 predicate_compare_name 是在 sys.dm_xe_objects 檢視表中定義為 object_type 'pred_compare' 的全域來源。
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 是動作。動作會出現在 sys.dm_xe_objects 檢視表中當做 object_type 'target'。
SET { target_parameter_name = <value> [, ...n] }	設定目標參數。目標參數會出現在 sys.dm_xe_object_columns 檢視中當做 column_type 'customizable ' 和 object_name = target_name。 重要事項 如果是使用信號緩衝區目標，建議您將 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 是以 KB 來指定，允許的大小下限為 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 引數無法用於相同的陳述式內。

權限

需要 CONTROL SERVER 權限。

範例

下列範例會啟動事件工作階段、取得某些即時工作階段統計資料，然後將兩個事件加入至現有工作階段中。

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

變更記錄

更新的內容
已更正 MAX_DISPATCH_LATENCY 引數的預設值。
已在 SET { target_parameter_name = <value> [, ...n] } 描述中加入重要注意事項。

請參閱

參考

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 擴充的事件目標