CREATE EVENT SESSION (Transact-SQL)

適用於：SQL Server Azure SQL 資料庫 Azure SQL 受控執行個體

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

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

語法

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';

重要

如果您使用信號緩衝區目標，建議您將目標參數（不同於MAX_MEMORY會話參數）設定MAX_MEMORY為 1024 KB（KB）或更少，以協助避免 XML 輸出可能的數據截斷。

如需目標類型的詳細資訊，請參閱 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在事件會話處於使用中狀態時，可能會導致可偵測的效能問題。 當使用者連接在等候事件從緩衝區排清時，可能會停滯。

注意

從 2024 年 6 月起，針對 Azure SQL 資料庫 和 Azure SQL 受控執行個體 中的事件檔案目標，自 2024 年 6 月起，NO_EVENT_LOSS的行為與ALLOW_SINGLE_EVENT_LOSS相同。 如果您指定NO_EVENT_LOSS，則訊息標識符為 25665、嚴重性 10 的警告，且此 目標不支援NO_EVENT_LOSS事件保留模式。會改用ALLOW_SINGLE_EVENT_LOSS保留模式。 會傳回 ，並建立會話。

這項變更可避免連線逾時、故障轉移延遲和其他問題，當NO_EVENT_LOSS與 Azure Blob 記憶體中的事件檔案目標搭配使用時，可能會降低資料庫可用性。

在未來 Azure SQL 資料庫 和 Azure SQL 受控執行個體 更新中，NO_EVENT_LOSS將會移除為支援的EVENT_RETENTION_MODE自變數。 請避免在新的開發工作中使用這項功能，並規劃修改目前使用這項功能的應用程式。

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之外，還會建立兩個 大小 緩衝區，而用於事件緩衝處理的總記憶體會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。

權限

在 SQL Server 和 SQL 受管理執行個體 上，需要 CREATE ANY EVENT SESSION [SQL Server 2022] 或 ALTER ANY EVENT SESSION 許可權。

在 SQL Database 上，資料庫需要 ALTER ANY DATABASE EVENT SESSION 權限。

提示

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

範例

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 資料庫與 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] 資料夾底下。

注意

建議針對受控執行個體使用伺服器範圍工作階段。 SSMS 中的物件總管並不會針對 Azure SQL 受控執行個體顯示資料庫範圍工作階段。 使用受控執行個體時，只能使用 Transact-SQL 來查詢及管理資料庫範圍工作階段。

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

SQL Server 和 Azure SQL 受控執行個體中的名稱	Azure SQL 資料庫和 Azure SQL 受控執行個體中的名稱
server_event_notifications server_event_session_actions server_event_session_events server_event_session_fields server_event_session_targets server_event_sessions server_events server_trigger_events	database_event_session_actions database_event_session_events database_event_session_fields database_event_session_targets database_event_sessions

上表中兩個清單截至 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)