ALTER EVENT SESSION (Transact-SQL)

適用於:SQL ServerAzure SQL 受控執行個體

啟動或停止事件工作階段,或是變更事件工作階段組態。

Transact-SQL 語法慣例

Syntax

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

注意

若要檢視 SQL Server 2014 (12.x) 和舊版的 Transact-SQL 語法,請參閱 舊版檔

引數

詞彙 定義
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 = 事件工作階段不會在啟動時啟動。

備註

不可在同一個陳述式內同時使用 ADDDROP 引數。

權限

需要 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)
SQL Server 擴充的事件目標
sys.server_event_sessions (Transact-SQL)
sys.dm_xe_objects (Transact-SQL)
sys.dm_xe_object_columns (Transact-SQL)