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_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 = <值> [ ,...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> 在事件工作階段中必須是有效的。

ADD TARGET <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 = <值> [, ...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 引數。

權限

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