ALTER EVENT SESSION (Transact-SQL)

適用於：SQL Server Azure 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，則此事件不會發生動作和目標處理。 述詞表達式限制為 3,000 個字元，這會限制字元串自變數。
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目標參數設定為 2,048 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 不允許事件遺失。 此選項可確保會保留所有引發的事件。 使用這個選項可強制引發事件的所有工作一直等候到事件緩衝區中有可用的空間為止。 這樣可能會在事件工作階段為使用中時偵測到效能問題。 當使用者連接在等候事件從緩衝區排清時，可能會停滯。 對於 Azure SQL 資料庫 中的事件檔案目標，其行為與ALLOW_SINGLE_EVENT_LOSS相同。 如需詳細資訊，請參閱 EVENT_RETENTION_MODE。
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 自變數不能用在相同的語句中。

權限

需要 ALTER ANY EVENT SESSION 權限。

提示

SQL Server 2022 為擴充事件引進了許多更細微的新許可權，如需詳細資訊，請參閱 部落格：SQL Server 2022 和 Azure SQL 的新細微許可權，以改善對 PoLP 的遵循。

範例

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

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