CREATE EVENT SESSION (Transact-SQL)

適用於：SQL ServerAzure SQL DatabaseAzure SQL 受控執行個體

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

Transact-SQL 語法慣例 (部分機器翻譯)

Syntax

CREATE EVENT SESSION event_session_name
ON { SERVER | DATABASE }
{  
    <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 是事件物件。

事件會以 object_type 'event' 的形式出現在 sys.dm_xe_objects 檢視中。

SET { event_customizable_attribute= <value> [ ,...n] }

允許為此事件設定可自訂的屬性。 可自訂的屬性會以 column_type 'customizable ' 與 object_name = event_name 的形式出現在 sys.dm_xe_object_columns 檢視中。

ACTION ( { [event_module_guid].event_package_name.action_name [ ,...n] })

要關聯至事件工作階段的動作，其中：

• event_module_guid 為包含此事件之模組的 GUID。
• event_package_name 是包含此動作物件的套件。
• action_name 是動作物件。

動作會以 object_type 'action' 的形式出現在 sys.dm_xe_objects 檢視中。

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' 的全域來源。

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

設定目標參數。

若要查看所有目標參數及其描述，請執行下列查詢，以 target-name 目標名稱取代佔位元，例如 event_file、 ring_buffer、 histogram等。

SELECT name AS target_parameter_name,
       column_value AS default_value,
       description
FROM sys.dm_xe_object_columns
WHERE column_type = 'customizable'
      AND
      object_name = 'target-name';

如需目標類型的詳細資訊，請參閱 SQL Server 中擴充事件的目標。

WITH ( <event_session_options> [ ,...n] )

指定要搭配事件工作階段使用的選項。

MAX_MEMORY =size [ KB | MB ]

指定為了事件緩衝處理而配置給工作階段的最大記憶體數量。 預設值是 4 MB。size 是整數值，可以是 KB 或 MB 值。 最大金額不能超過 2 GB（小於 2,048 MB）。 不過，不建議在 GB 範圍內使用記憶體值。

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 不允許事件遺失。 此選項可確保會保留所有引發的事件。 使用這個選項可強制引發事件的所有工作一直等候到事件緩衝區中有可用的空間為止。 使用NO_EVENT_LOSS在事件會話處於使用中狀態時，可能會導致可偵測的效能問題。 當使用者連接在等候事件從緩衝區排清時，可能會停滯。

MAX_DISPATCH_LATENCY = { seconds SECONDS | INFINITE }

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

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

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之外，還會建立兩個 大小 緩衝區，而用於事件緩衝處理的總記憶體會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 啟動時，是否要自動啟動這個事件工作階段。

ON 事件工作階段會在啟動時啟動。

OFF 事件會話未在啟動時啟動。

備註

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

權限

在 SQL Server 與 SQL 受控執行個體上，需要 ALTER ANY EVENT SESSION 權限。 在 SQL Database 上，資料庫需要 ALTER ANY DATABASE EVENT SESSION 權限。

範例

SQL 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

Azure SQL 範例

在 Azure SQL 受控執行個體或 Azure SQL Database 中，將 .xel 檔案儲存在 Azure Blob 儲存體中。 您可以使用 sys.fn_xe_file_target_read_file 從您自己建立的擴充事件工作階段中讀取，並儲存在 Azure Blob 儲存體中。 如需範例逐步解說，請檢閱 Azure SQL Database 與 Azure SQL 受控執行個體中擴充事件的事件檔案目標程式碼 (部分機器翻譯)。

Azure SQL Database 與 SQL 受控執行個體的程式碼範例可能會有所不同

針對 SQL Server 撰寫的一些 Transact-SQL 程式代碼範例，需要在 Azure 中執行小型變更。 這類程式代碼範例的其中一個類別涉及目錄檢視，其名稱前置詞會根據資料庫引擎類型而有所不同：

• server_ - SQL Server 和 Azure SQL 受控執行個體 的前置詞
• database_ - Azure SQL 資料庫 和 SQL 受管理執行個體 的前置詞

Azure SQL 資料庫 僅支持資料庫範圍的事件會話。 SQL Server Management Studio （SSMS） 完全支援 Azure SQL 資料庫 的資料庫範圍事件會話：包含資料庫範圍會話的擴充事件節點會出現在 物件總管 中的每個資料庫底下。

Azure SQL 受控執行個體同時支援資料庫範圍工作階段與伺服器範圍工作階段。 SSMS 完全支援適用於 SQL 受控執行個體的伺服器範圍工作階段：包含所有伺服器範圍工作階段的擴充事件節點會出現在物件總管中每個受控執行個體的 [Management] 資料夾底下。

為了說明，下表列出並比較兩個目錄檢視子集。 為求簡潔，這些子集限制為同時包含字串 _event 的檢視名稱。 子集具有不同的名稱前置詞，因為它們支援不同的資料庫引擎類型。

上表中兩個清單截至 2022 年 3 月為止是準確的。 如需最新的清單，請執行下列 Transact-SQL SELECT 語句：

SELECT name
    FROM sys.all_objects
    WHERE
        (name LIKE 'database[_]%' OR
         name LIKE 'server[_]%' )
        AND name LIKE '%[_]event%'
        AND type = 'V'
        AND SCHEMA_NAME(schema_id) = 'sys'
    ORDER BY name;

另請參閱

• sys.server_event_sessions (Transact-SQL)
• sys.dm_xe_objects (Transact-SQL)
• sys.dm_xe_object_columns (Transact-SQL)

下一步

• ALTER EVENT SESSION (Transact-SQL)
• DROP EVENT SESSION (Transact-SQL)