CREATE EVENT SESSION (Transact-SQL)

建立擴充的事件工作階段，可識別事件的來源、事件工作階段目標及事件工作階段選項。

Transact-SQL 語法慣例。

語法

CREATE EVENT SESSION event_session_name
ON SERVER
{
    <event_definition> [ ,...n]
    [ <event_target_definition> [ ,...n] ]
    [ WITH ( <event_session_options> [ ,...n] ) ]
}
;
  
<event_definition>::=
{
    ADD EVENT [event_module_guid].event_package_name.event_name 
         [ ( { 
                 [ SET { event_customizable_attribute = <value> [ ,...n] } ]
                 [ ACTION ( { [event_module_guid].event_package_name.action_name [ ,...n] } ) ]
                 [ WHERE <predicate_expression> ]
        } ) ]
}
  
<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'
}

<event_target_definition>::=
{
    ADD TARGET [event_module_guid].event_package_name.target_name
        [ ( SET { target_parameter_name = <value> [ ,...n] } ) ]
}

<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
  為事件工作階段的使用者定義名稱。event_session_name 是英數字元，最多可以到 128 個字元，而且在 SQL Server 執行個體內必須是唯一的，且必須符合識別碼的規則。

• ADD EVENT [ 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' 的全域來源。

• number
  這是包含 decimal 的任何數值類型。限制為缺少可用的實體記憶體，或是數字太大而不能表示為 64 位元整數。

• 'string'
  ANSI 或 Unicode 字串 (依述詞比較的需求而定)。不會針對述詞比較函數執行隱含字串類型轉換。傳遞錯誤的類型會產生錯誤。

• ADD TARGET [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 擴充的事件目標＞。

• WITH ( <event_session_options> [ ,...n] )
  指定要搭配事件工作階段使用的選項。

• MAX_MEMORY = size [ KB | MB ]
  指定為了事件緩衝處理而配置給工作階段的最大記憶體數量。預設值是 4 MB。size 是整數值，可以是 KB 或 MB 值。

• 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 }
  指定事件在分派給事件工作階段目標之前，將於記憶體內緩衝處理的時間量。依預設，此值設定為 30 秒。

  • seconds SECONDS
    在開始將緩衝區排清到目標之前等候的時間 (秒數)，seconds 是整數值。最小的延遲值是 1 秒鐘。但是，可使用 0 來指定 INFINITE 延遲。

  • 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
    事件工作階段不會在啟動時啟動。

備註

邏輯運算子的優先順序是 NOT (最高)，後面依序接著 AND 和 OR。

權限

需要 CONTROL SERVER 權限。

範例

以下範例將示範如何建立名為 test_session 的事件工作階段。這個範例會加入兩個事件，並使用 Windows 事件追蹤目標。

IF EXISTS(SELECT * FROM sys.server_event_sessions WHERE name='test_session')
    DROP EVENT session test_session ON SERVER;
GO
CREATE EVENT SESSION test_session
ON SERVER
    ADD EVENT sqlos.async_io_requested,
    ADD EVENT sqlserver.lock_acquired
    ADD TARGET package0.etw_classic_sync_target 
        (SET default_etw_session_logfile_path = N'C:\demo\traces\sqletw.etl' )
    WITH (MAX_MEMORY=4MB, MAX_EVENT_SIZE=4MB);
GO

變更記錄

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

請參閱

參考

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