擴充事件目標

適用於：SQL Server Azure SQL Database Azure SQL Managed Instance Microsoft Fabric 中的 SQL 資料庫

本文說明何時及如何使用擴充事件目標。對於每個目標，本文描述：

其收集和報告事件數據的能力
使用目標的事件工作階段範例

下表說明不同 SQL 平台中每個目標類型的可用性。

目標類型	SQL Server	Fabric 中的 Azure SQL 資料庫和 SQL 資料庫	Azure SQL 受控執行個體
事件檔案	是	是	是
ring_buffer（環狀緩衝區）	是	是	是
event_stream	是	是	是
色階分佈圖	是	是	是
事件計數器	是	是	是
配對匹配	是	無	無
etw_classic_sync_target（經典同步目標）	是	無	無

除非另有說明，否則目標會以非同步方式處理接收的資料。

若要充分利用本文，您應：

熟悉擴充事件基本概念，如快速入門：擴充事件中所述。
使用最新版本的 SQL Server Management Studio （SSMS）。

event_file 目標

目標 event_file 將事件會話的輸出從記憶體緩衝區寫入至磁碟檔案或 Azure 儲存體中的 Blob。

您可以在 filename 子句中指定 ADD TARGET 參數。副檔名必須是 xel。
系統會使用您選擇的檔案名稱作為前綴，並附加根據日期時間生成的數值，後面接著 xel 副檔名。
您可以選擇性地指定 MAX_FILE_SIZE 參數。它定義了在建立新檔案之前檔案可以增長到的大小上限（以兆位元組（MB）為單位）。
您可以選擇性地指定選項 MAX_ROLLOVER_FILES ，以選擇除了目前檔案之外，要保留在檔案系統中的檔案數目上限。預設值是 UNLIMITED。評估時 MAX_ROLLOVER_FILES ，如果檔案數目超過 MAX_ROLLOVER_FILES 設定，則會刪除較舊的檔案。

這很重要

視新增至階段作業的事件而定，目標所 event_file 產生的檔案可能包含機密資料。仔細檢查檔案系統並共用目錄和單一 .xel 檔案的權限，包括繼承的存取權限，以避免授予不必要的讀取權限。遵循最小權限原則。若要降低不小心收集敏感資料的風險，請避免持續時間長的事件會話（如果它們可能會收集敏感資料）。

注意

Azure SQL 資料庫和 Azure SQL 受控執行個體僅支援將 Azure 儲存體中的 Blob 作為 filename 參數的值。如需 event_file Azure SQL 資料庫、Fabric 中的 SQL 資料庫或 Azure SQL 受控執行個體的程式碼範例，請參閱在 Azure 儲存體中使用 event_file 目標建立事件工作階段。

在本機檔案系統中建立具有event_file目標的事件階段作業

如需使用本機檔案儲存體、SSMS 或 T-SQL 建立 event_file 事件工作階段的操作指南，請參閱快速入門：擴充事件。

在 Azure 儲存體中建立具有event_file目標的事件工作階段

如需如何在 Azure 儲存體中建立儲存體帳戶的詳細描述，請參閱建立儲存體帳戶。您可以使用 Azure 入口網站、PowerShell、Azure SQL、ARM 範本或 Bicep 範本來建立儲存體帳戶。使用符合以下條件的帳戶：

是一個 Standard general-purpose v2 帳戶。
使用 HotBlob 存取層。
如果在 Azure 虛擬機器（Azure VM）中使用 SQL Server，儲存體帳戶應該與 Azure VM 位於相同的 Azure 區域中。
未啟用階層式命名空間。

接下來，使用 Azure 入口網站在此儲存體帳戶中建立容器。您也可以使用 PowerShell 或使用 Azure CLI 建立容器。

記下您建立的 儲存體帳戶 和容器名稱。您可以在下列步驟中使用它們。

若要讀取和寫入事件資料，資料庫引擎需要特定的存取權。您可以根據您選擇的驗證類型，以不同的方式授與此存取權：受控識別或具有共用存取簽章（SAS）權杖的秘密型驗證。

若要向 Azure 儲存體進行驗證，資料庫引擎需要伺服器範圍的認證或資料庫範圍的認證，這會告訴它要使用的驗證類型，並提供秘密型驗證的秘密。建立此認證 CONTROL 需要資料庫許可權。

針對 SQL Server 和 Azure SQL 受控執行個體，此權限在 master 資料庫中是必要的。依預設，權限由db_owner中的master資料庫角色成員，以及執行個體上sysadmin伺服器角色的成員持有。針對 Azure SQL 資料庫和 Fabric 中的 SQL 資料庫，此權限是由資料庫擁有者（dbo）、資料庫角色的 db_owner 成員，以及邏輯伺服器的系統管理員所持有。

建立認證之後，建立事件會話的其餘步驟不需要CONTROL權限。如需所需的特定許可權，請參閱許可權。

使用受控識別授與存取權

如果搭配 Microsoft Entra 驗證使用受控識別，您可以將容器的 儲存體 Blob 資料參與者 RBAC 角色指派給資料庫引擎所使用的受控識別。如需詳細資訊，請參閱下列以 SQL 平台為基礎的內容：

Azure SQL 資料庫邏輯伺服器的受控識別。
Azure SQL 受控執行個體的受管理身份。
Azure VM 上裝載 SQL Server 執行個體之受管理身份。如需詳細資訊，請參閱 Azure 資源的受控識別如何與 Azure 虛擬機器搭配使用。
已啟用 Arc 的 SQL Server 執行個體的受控識別。

RBAC 角色指派就緒之後，請使用下列步驟：

使用 T-SQL 建立認證。

執行下列 T-SQL 批次之前，請進行下列變更：

在https://<storage-account-name>.blob.core.windows.net/<container-name>的所有三次出現中，將<storage-account-name>替換成您的儲存體帳戶名稱，並將<container-name>替換成容器的名稱。請確定 URL 結尾沒有尾端斜線。

建立伺服器範圍的認證：（適用於 SQL Server、Azure SQL 受控執行個體）

使用 SSMS 等用戶端工具，開啟新的查詢視窗，連線到 master 您要建立事件會話的執行個體上的資料庫，然後貼上下列 T-SQL 批次。

/* The name of the credential must match the URL of the blob container. */
IF EXISTS (SELECT 1
           FROM sys.credentials
           WHERE name = 'https://<storage-account-name>.blob.core.windows.net/<container-name>')
    DROP CREDENTIAL
        [https://<storage-account-name>.blob.core.windows.net/<container-name>];

/* When using managed identity, the credential does not contain a secret */
CREATE CREDENTIAL
    [https://<storage-account-name>.blob.core.windows.net/<container-name>]
    WITH IDENTITY = 'MANAGED IDENTITY';

建立資料庫範圍的認證：（適用於 Azure SQL 資料庫、Azure SQL 受控執行個體、Fabric 中的 SQL 資料庫）

使用 SSMS 等用戶端工具，開啟新的查詢視窗、連線到您建立事件會話的使用者資料庫，然後貼上下列 T-SQL 批次。請確定您已連線到您的使用者資料庫，而不是連線到 master 資料庫。

/* The name of the credential must match the URL of the blob container. */
IF EXISTS (SELECT 1
           FROM sys.database_credentials
           WHERE name = 'https://<storage-account-name>.blob.core.windows.net/<container-name>')
    DROP DATABASE SCOPED CREDENTIAL
        [https://<storage-account-name>.blob.core.windows.net/<container-name>];

/* When using managed identity, the credential does not contain a secret */
CREATE DATABASE SCOPED CREDENTIAL
    [https://<storage-account-name>.blob.core.windows.net/<container-name>]
    WITH IDENTITY = 'MANAGED IDENTITY';

然後，請遵循步驟，在 SSMS 中使用 Azure 儲存體中的event_file目標建立事件會話。

使用共用存取簽章 (Shared Access Signature, SAS) 權杖提供存取權

如果使用 秘密型驗證，您可以為容器建立共用存取簽章（SAS）權杖。若要使用此驗證類型，必須針對儲存體帳戶啟用 [允許儲存體帳戶金鑰存取] 選項。如需詳細資訊，請參閱防止 Azure 儲存體帳戶使用共用金鑰授權。

在 Azure 入口網站中，流覽至您建立的儲存體帳戶和容器。選取容器，然後流覽至 [設定>] [共用存取權杖]。

SAS 權杖必須符合下列需求：
- 權限設定為 Read、 Write、 Delete。 List
- 開始時間和到期時間必須包含事件工作階段的存留期。您建立的 SAS 權杖只能在此時間間隔內運作。
- 針對 Azure SQL 資料庫、Azure SQL 受控執行個體和 Fabric 中的 SQL 資料庫，SAS 權杖必須沒有 IP 位址限制。
選取 [產生 SAS 權杖和 URL] 按鈕。 SAS 權杖位於 Blob SAS 權杖 方塊中。您可以複製它以在下一步中使用。

這很重要

SAS 權杖提供此容器的讀取和寫入存取權。像對待密碼或任何其他秘密一樣對待它。

建立認證，以使用 T-SQL 儲存 SAS 權杖。

在執行下列 T-SQL 批次之前，請進行下列變更：

如果建立伺服器範圍的認證並使用 CREATE MASTER KEY 陳述式，請取代 <password> 為保護主要金鑰的強式密碼。如需詳細資訊，請參閱 CREATE MASTER KEY。
在https://<storage-account-name>.blob.core.windows.net/<container-name>的所有三次出現中，將<storage-account-name>替換成您的儲存體帳戶名稱，並將<container-name>替換成容器的名稱。
在SECRET子句中，將<sas-token>替換為您在上一個步驟中複製的 SAS 認證。

建立伺服器範圍的認證：（適用於 SQL Server、Azure SQL 受控執行個體）

使用 SSMS 等用戶端工具，開啟新的查詢視窗，將它連線到 master 您建立事件工作階段之執行個體上的資料庫，然後貼上下列 T-SQL 批次。

/* Create a master key to protect the secret of the credential */
IF NOT EXISTS (SELECT 1
               FROM sys.symmetric_keys
               WHERE name = '##MS_DatabaseMasterKey##')
    CREATE MASTER KEY ENCRYPTION BY PASSWORD = '<password>'

/* The name of the credential must match the URL of the blob container. */;
IF EXISTS (SELECT 1
           FROM sys.credentials
           WHERE name = 'https://<storage-account-name>.blob.core.windows.net/<container-name>')
    DROP CREDENTIAL
        [https://<storage-account-name>.blob.core.windows.net/<container-name>];

/* The secret is the SAS token for the container. */
CREATE CREDENTIAL
    [https://<storage-account-name>.blob.core.windows.net/<container-name>]
WITH IDENTITY = 'SHARED ACCESS SIGNATURE',
    SECRET = '<sas-token>';

建立資料庫範圍的認證：（適用於 Azure SQL 資料庫、Azure SQL 受控執行個體、Fabric 中的 SQL 資料庫）

使用 SSMS 之類的用戶端工具，開啟新的查詢視窗、連線到您建立事件會話的資料庫，然後貼上下列 T-SQL 批次。請確定您已連線到您的使用者資料庫，而不是連線到 master 資料庫。

/* The name of the credential must match the URL of the blob container. */
IF EXISTS (SELECT 1
           FROM sys.database_credentials
           WHERE name = 'https://<storage-account-name>.blob.core.windows.net/<container-name>')
    DROP DATABASE SCOPED CREDENTIAL
        [https://<storage-account-name>.blob.core.windows.net/<container-name>];

/* The secret is the SAS token for the container. */
CREATE DATABASE SCOPED CREDENTIAL
    [https://<storage-account-name>.blob.core.windows.net/<container-name>]
WITH IDENTITY = 'SHARED ACCESS SIGNATURE',
    SECRET = '<sas-token>';

然後，請遵循下一節中的步驟，在 SSMS 中建立事件工作階段，並在 Azure 儲存體中使用 event_file 目標。

在 SSMS 中，使用 Azure 儲存體中的事件檔案目標建立事件會話

建立提供存取儲存容器的認證後，您就可以建立事件會話。與建立憑證不同，建立事件會話不需要 CONTROL 權限。即使您擁有更受限制的權限，建立憑證之後，您也可以建立事件會話。如需所需的特定許可權，請參閱許可權。

若要在 SSMS 中建立新的事件會話：

針對 SQL Server 和 Azure SQL 受控執行個體，展開 [管理] 資料夾底下的 [擴充事件] 節點。針對 Azure SQL 資料庫和 Fabric 中的 SQL 資料庫，展開資料庫底下的 [擴充事件 ] 節點。
以滑鼠右鍵按一下 Sessions 資料夾，然後選取 New Session...。
在 [ 一般 ] 頁面上，輸入工作階段的名稱，該名稱適用於 example-session 下列程式碼範例。
在 「事件」 頁面上，選取一或多個要新增至工作階段的事件。例如，您可以選取 sql_batch_starting 事件。
在 「資料儲存」 頁面上，選取 event_file 作為目標類型。將儲存容器的 URL 貼到儲存 URL 方塊中。在此 URL 結尾輸入正斜線（/），後面接著檔案（blob）名稱。例如： https://<storage-account-name>.blob.core.windows.net/<container-name>/example-session.xel 。
現在已設定工作階段，您可以選擇性地選取 [腳本] 按鈕來建立工作階段的 T-SQL 腳本，以儲存它以供日後使用。
選取 [確定] 以建立工作階段。
在 [物件總管] 中，展開 [工作階段] 資料夾，以查看您所建立的事件工作階段。根據預設，工作階段不會在建立時啟動。若要啟動工作階段，請以滑鼠右鍵按一下工作階段名稱，然後選取 [啟動工作階段]。您可以稍後在工作階段執行後選取 [停止工作階段] 來停止它。

執行 T-SQL 批次時，會話將 sql_batch_starting 事件寫入儲存體容器中的 example-session.xel Blob 資料。

注意

針對 SQL 受控執行個體，請使用 [指令碼] 按鈕來建立工作階段的 T-SQL 指令碼，而不是貼上 [資料儲存體] 頁面上的儲存體容器網址。將容器 URL 指定為 filename 參數的值，並執行腳本以建立會話。

在 T-SQL 的 Azure 儲存體中建立具有event_file目標的事件工作階段

以下是包含一個基於 Azure 儲存體的 CREATE EVENT SESSION 目標的 ADD TARGETevent_file 子句範例。

CREATE EVENT SESSION [example-session]
ON SERVER
ADD EVENT sqlserver.sql_batch_starting
ADD TARGET package0.event_file
(
    SET filename = N'https://<storage-account-name>.blob.core.windows.net/<container-name>/example-session.xel'
)
GO

若要在 Azure SQL 資料庫或 Fabric 中的 SQL 資料庫中使用此範例，請將取代 ON SERVER 為 ON DATABASE。

針對 Azure 儲存體中 event_file 目標的事件會話進行疑難排解

下列清單包含您在啟動使用 Azure 儲存體的擴充事件工作階段時可能會遇到的錯誤，以及錯誤的可能說明。

作業系統傳回錯誤 5：「存取被拒絕」。
- 如果使用受控識別驗證：
  - 資料庫引擎所使用的受控識別沒有必要的 RBAC 角色指派。如需詳細資訊，請參閱使用受控識別授與存取權。
  - 儲存體帳戶防火牆已啟用，而且也已啟用允許受信任 Azure 服務存取儲存體帳戶的例外狀況，但 Microsoft.Sql/servers 邏輯伺服器的資源執行個體尚未新增至授與存取權的資源執行個體清單。如需詳細資訊，請參閱授與 Azure 資源執行個體的存取權。
  - 如果使用強制模式的網路安全性周邊，資料庫和儲存體帳戶不會位於相同的周邊中。
- 如果使用 SAS 權杖驗證：
  - 儲存體帳戶防火牆已啟用。使用 SAS 權杖驗證的事件工作階段不支援此功能。
  - SAS 權杖沒有足夠的許可權，或已過期。如需詳細資訊，請參閱使用 SAS 權杖授與存取權。
  - 如果使用處於強化模式的網路安全性周邊，則未設置允許資料庫不受限制地向外發送通訊及接受來自儲存體帳戶的不受限制的輸入通訊的存取規則。
作業系統傳回錯誤 86：「指定的網路密碼不正確。」
- 沒有名為匹配 Blob 容器 URL 的資料庫範圍認證（適用於 Azure SQL 資料庫）或伺服器範圍認證（適用於 Azure SQL 受控執行個體或 SQL Server）。如需詳細資訊，請參閱使用受控識別授與存取權或使用 SAS 權杖授與存取權的範例。
- 認證名稱以斜線（）/ 結尾。認證名稱應以容器名稱結尾，不包含尾端斜線。
作業系統傳回錯誤 3：「系統找不到指定的路徑。」
- Blob 容器 URL 中指定的容器不存在。
作業系統傳回錯誤 13：「資料無效。」
- Blob 容器上有不變性原則。事件工作階段不支援不可變儲存體。
- 儲存體帳戶已啟用階層式命名空間。事件會話不支援已啟用階層式命名空間的儲存帳戶。

sys.fn_xe_file_target_read_file() 函數

event_file 目標會將接收到的資料儲存為人類無法讀取的二進位格式。此 sys.fn_xe_file_target_read_file 函式可讓您將檔案的內容 xel 表示為關聯式資料列集。如需詳細資訊，包括使用範例，請參閱 sys.fn_xe_file_target_read_file。

ring_buffer 目標

目標物件很 ring_buffer 有用，可以快速啟動事件會話，並僅在記憶體中進行事件資料收集。當事件使用環形緩衝區中的可用記憶體時，會捨棄較舊的事件。當您停止事件會話時，所有會話輸出到 ring_buffer 目標位置的內容也會被捨棄。

您可將資料轉換成 XML，以取用 ring_buffer 目標中的資料，如下列範例所示。在此轉換期間，會省略任何不符合 4 MB XML 文件的資料。因此，即使您使用較大的 MAX_MEMORY 值，來擷取通道緩衝區中的更多事件 (或將此參數保留為預設值)，您可能也無法取用所有事件，因為 XML 檔大小有 4 MB 的限制，請考慮 XML 標記和 Unicode 字符串的額外負荷。

您知道，如果 XML 檔案中的 truncated 屬性設定為 1，則會在轉換成 XML 期間省略通道緩衝區的內容，例如：

<RingBufferTarget truncated="1" processingTime="0" totalEventsProcessed="284" eventCount="284" droppedCount="0" memoryUsed="64139">

提示

新增 ring_buffer 目標時，請將其 MAX_MEMORY 參數設定為 1,024 KB 或更少。使用較大的值可能會不必要地增加記憶體使用量。

根據預設，MAX_MEMORY 目標在 SQL Server 中沒有被限制，而在 Azure SQL 資料庫、Azure SQL 受控執行個體和 Fabric 中的 SQL 資料庫會限制為 32 MB。

建立具有「ring_buffer」目標的事件工作階段

以下是建立事件工作階段範例，其中 ring_buffer 作為目標，以收集 lock_acquired 事件，並將環形緩衝區中的事件總數限制為上限 100。在此範例中，參數 MAX_MEMORY 會出現兩次：一次將目標記憶體設定 ring_buffer 為 1,024 KB，一次將事件工作階段緩衝區記憶體設定為 2 MB。

若要在 Azure SQL 資料庫或 Fabric 中的 SQL 資料庫中使用此範例，請將取代 ON SERVER 為 ON DATABASE。

CREATE EVENT SESSION ring_buffer_lock_acquired
ON SERVER
ADD EVENT sqlserver.lock_acquired
ADD TARGET package0.ring_buffer
(
SET MAX_EVENTS_LIMIT = 100,
    MAX_MEMORY = 1024
)
WITH
(
    MAX_MEMORY = 2 MB,
    MAX_DISPATCH_LATENCY = 3 SECONDS
);

若要啟動事件工作階段，請執行下列陳述式：

ALTER EVENT SESSION ring_buffer_lock_acquired
ON SERVER
STATE = START;

在 SSMS 中若要檢視環形緩衝區中收集的事件資料，請展開會話節點並選取 package0.ping_buffer 目標。資料會以 XML 顯示。

若要在會話活躍時檢視關聯式資料列集中目標的 ring_buffer 事件資料，您可以使用 XQuery 表示式將 XML 轉換成關聯式資料。例如：

;WITH
/* An XML document representing memory buffer contents */
RingBuffer AS
(
    SELECT CAST (xst.target_data AS XML) AS TargetData
    FROM sys.dm_xe_session_targets AS xst
         INNER JOIN sys.dm_xe_sessions AS xs
             ON xst.event_session_address = xs.address
    WHERE xs.name = N'ring_buffer_lock_acquired'
),
/* A row for each event in the buffer, represented as an XML fragment */
EventNode AS
(
    SELECT CAST (NodeData.query('.') AS XML) AS EventInfo
    FROM RingBuffer AS rb
    CROSS APPLY rb.TargetData.nodes('/RingBufferTarget/event') AS n(NodeData)
)

/* A relational rowset formed by using the XQuery value method */
SELECT EventInfo.value('(event/@timestamp)[1]','datetimeoffset') AS timestamp,
       EventInfo.value('(event/@name)[1]','sysname') AS event_name,
       EventInfo.value('(event/data/value)[1]','nvarchar(max)') AS sql_batch_text
FROM EventNode
ORDER BY timestamp DESC;

event_stream 目標

event_stream 目標僅可用於 C# 這類語言所撰寫的 .NET 程式。開發人員可以透過命名空間中的 Microsoft.SqlServer.XEvents.Linq .NET Framework 類別存取事件串流。此目標隱含地存在於任何事件會話中。無法使用 T-SQL 新增它。

如需詳細資訊，請參閱 sys.fn_MSxe_read_event_stream。

The event data stream was disconnected because there were too many outstanding events. To avoid this error either remove events or actions from your session or add a more restrictive predicate filter to your session. 從 event_stream 目標讀取時如果您遇到錯誤 25726，這表示填入資料速度比用戶端還要快的事件資料流可能會取用資料。這會導致資料庫引擎與事件串流中斷連線，以避免影響伺服器引擎效能。

色階分佈圖目標

histogram目標會計算欄位或動作中相異值的事件出現次數。對於每個相異值，會使用個別的計數儲存區。目標histogram會同步處理接收到的資料。

參數 SOURCE_TYPE 控制目標 histogram 的行為。

SOURCE_TYPE = 0：收集事件欄位的資料。
SOURCE_TYPE = 1：收集動作的資料。這是預設值。

參數 SLOTS 的預設值為 256。如果您指派另一個值，值會四捨五入至下一個 2 的次方。例如， SLOTS = 59 會四捨五入為 64。目標的 histogram 直方圖插槽數目上限為 16,384。

使用 histogram 做為目標時，您可能有時會看到非預期結果。某些事件可能不會出現在預期插槽中，而其他插槽可能會顯示高於預期的事件計數。如果將事件指派給插槽時發生雜湊衝突，就會發生這種情況。雖然這是罕見的，但如果發生雜湊衝突，則應在某個插槽中計數的事件會在另一個插槽中計數。出於此原因，假設事件未發生只是因為特定插槽中的計數顯示為零，則應謹慎處理。

例如，請設想下列情境：

您設定了一個擴充事件工作階段，使用 histogram 作為目標，並將事件按 object_id 分類，以收集預存程序執行的統計資料。
您執行預存程序 A。然後，您執行預存程序 B。

如果雜湊函式對兩個預存程序回傳相同的值，則直方圖會顯示object_id執行兩次，而A未出現。

若要在相異值數目相對較小時緩解此問題，請將色階分佈圖插槽的數目設定為高於預期相異值的平方。例如，如果 histogram 目標已將其 SOURCE 設定為 table_name 事件字段，且資料庫中有 20 個資料表，則 20*20 = 400。下一個大於 400 的等級是 512，這是此範例中建議的插槽數目。

每個 histogram 目標都接受來自單一來源（事件欄位或動作）的資料，且僅包含一個直方圖。無法對每個事件工作階段，新增超過一個相同類型的目標。每個 histogram 目標也無法有多個來源類型。因此，需要新的事件階段作業，才能追蹤個別 histogram 目標中的不同動作或事件欄位。

建立具有直方圖目標的事件工作階段

以下是使用 histogram 目標建立事件工作階段的範例。

若要在 Azure SQL 資料庫或 Fabric 中的 SQL 資料庫中使用此範例，請將取代 ON SERVER 為 ON DATABASE。

CREATE EVENT SESSION histogram_lock_acquired
ON SERVER
ADD EVENT sqlserver.lock_acquired
(
    ACTION (sqlos.system_thread_id)
)
ADD TARGET package0.histogram
(
    SET FILTERING_EVENT_NAME = N'sqlserver.lock_acquired',
        SLOTS = 16,
        SOURCE = N'sqlos.system_thread_id',
        SOURCE_TYPE = 1
);

在 ADD TARGET ... (SET ...) 子句中，目標參數 SOURCE_TYPE 被設定為 1，這表示 histogram 目標正在追蹤一個動作。

子句將 ADD EVENT ... (ACTION ...) 動作新增至 sqlos.system_thread_id 事件。參數 SOURCE 設定為， sqlos.system_thread_id 以使用此動作所收集的系統執行緒 ID 作為目標的資料 histogram 來源。在此範例中，每當工作階段處於作用中時，histogram 目標會計算每個系統執行緒取得鎖定的 lock_acquired 事件數目。

若要啟動事件工作階段，請執行下列陳述式：

ALTER EVENT SESSION histogram_lock_acquired
ON SERVER
STATE = START;

若要在 SSMS 中檢視收集的直方圖資料，請展開工作階段節點，然後選取 package0.histogram 目標。資料會呈現在兩欄佈局中。每一行代表具有不同值的分組以及出現次數。

以下是此範例中目標histogram可能會擷取的資料呈現的樣子。 value 資料行中的值為 system_thread_id 值。例如，系統執行緒 6540 總共取得 236 個鎖定。

value   count
-----   -----
 6540     236
 9308      91
 9668      74
10144      49
 5244      44
 2396      28

以下是使用 T-SQL 從目標讀取 histogram 數據的範例：

WITH histogram_target
AS (SELECT TRY_CAST (st.target_data AS XML) AS target_data
    FROM sys.dm_xe_sessions AS s
         INNER JOIN sys.dm_xe_session_targets AS st
             ON s.address = st.event_session_address
    WHERE s.name = 'event-session-name-placeholder'),
 histogram
AS (SELECT hb.slot.value('(@count)[1]', 'bigint') AS slot_count,
           hb.slot.value('(value/text())[1]', 'nvarchar(max)') AS slot_value
    FROM histogram_target AS ht
CROSS APPLY ht.target_data.nodes('/HistogramTarget/Slot') AS hb(slot))
SELECT slot_value,
       slot_count
FROM histogram;

event_counter 目標

event_counter 目標會計算每個所指定事件的發生次數。

event_counter目標沒有參數，並同步處理接收到的資料。

建立具備事件計數器目標的事件會話

以下是使用 event_counter 目標建立事件工作階段的範例。工作階段會計算前四個 checkpoint_begin 事件，然後停止計算，因為其述詞將傳送至目標的事件數目限制為四個。您可以執行checkpoint_begin命令來產生CHECKPOINT此範例的事件。

若要在 Azure SQL 資料庫或 Fabric 中的 SQL 資料庫中使用此範例，請將取代 ON SERVER 為 ON DATABASE。

CREATE EVENT SESSION event_counter_checkpoint_begin
ON SERVER
ADD EVENT sqlserver.checkpoint_begin
(
    WHERE package0.counter <= 4
)
ADD TARGET package0.event_counter
WITH
(
    MAX_MEMORY = 4096 KB,
    MAX_DISPATCH_LATENCY = 3 SECONDS
);

若要啟動事件工作階段，請執行下列陳述式：

ALTER EVENT SESSION event_counter_checkpoint_begin
ON SERVER
STATE = START;

若要在 SSMS 中檢視收集的資料，請展開事件節點，然後選取 package0.event_counter 目標物件。資料會顯示在三欄格線中。每一列代表一個事件及其出現次數。

以下是此範例中 event_counter 目標所擷取的資料在經過四個檢查點後可能的樣貌。

package_name   event_name         count
------------   ----------------   -----
sqlserver      checkpoint_begin   4

pair_matching 目標

pair_matching 目標可讓您偵測沒有對應結束事件的開始事件。例如，您可以找到沒有 lock_acquired 相符 lock_released 事件的事件，這可能表示長時間執行的交易正在保留鎖定。

Extended Events 不會自動比對開始和結束事件。相反地，您應在pair_matching陳述式的CREATE EVENT SESSION目標規格中定義比對邏輯。當開始事件和結束事件相符時，目標系統會捨棄該對，但會保留不相符的開始事件。

建立具有pair_matching目標的事件工作階段

在這個範例中，我們建立一個名為 T1的範例表，插入三行，並取得 object_id 該表的值。為簡單起見，我們在此範例中在資料庫中 tempdb 建立資料表。如果您使用不同的資料庫，請在下列 T-SQL 範例程式碼中調整資料庫名稱。

CREATE TABLE T1 (id INT PRIMARY KEY);

INSERT INTO T1 (id)
VALUES (1), (2), (3);

SELECT OBJECT_ID('T1') AS object_id;
-- object_id = 1029578706

下列活動場次會收集兩個事件，lock_acquired以及lock_released。它還有兩個目標。一個是 event_counter 提供每個事件出現次數的目標。另一個是目標， pair_matching 它定義了將開始 lock_acquired 事件和結束 lock_released 事件配對成對的邏輯。

指派給 BEGIN_MATCHING_COLUMNS 和 END_MATCHING_COLUMNS 的一串逗號分隔欄位必須相同。雖然允許使用空格，但是逗號分隔值中所提及的欄位之間不允許定位字元或換行字元。

在事件會話定義中，我們使用事件謂詞來僅收集資料庫中 tempdb 事件中的與 object_id 表 T1的物件 ID 相符的那些事件。調整子句中的 WHERE 述詞，以使用資料表的物件識別碼。

若要在 Azure SQL 資料庫或 Fabric 中的 SQL 資料庫中使用此範例，請將取代 ON SERVER 為 ON DATABASE。

CREATE EVENT SESSION pair_matching_lock_acquired_released
ON SERVER
ADD EVENT sqlserver.lock_acquired
(
    SET COLLECT_DATABASE_NAME = 1,
        COLLECT_RESOURCE_DESCRIPTION = 1
    ACTION (sqlserver.transaction_id)
    WHERE (database_name = 'tempdb'
           AND object_id = 1029578706)
),
ADD EVENT sqlserver.lock_released
(
    SET COLLECT_DATABASE_NAME = 1,
        COLLECT_RESOURCE_DESCRIPTION = 1
    ACTION (sqlserver.transaction_id)
    WHERE (database_name = 'tempdb'
           AND object_id = 1029578706)
)
ADD TARGET package0.event_counter,
ADD TARGET package0.pair_matching
(
    SET BEGIN_EVENT = N'sqlserver.lock_acquired',
        BEGIN_MATCHING_COLUMNS = N'resource_0, resource_1, resource_2, transaction_id, database_id',
        END_EVENT = N'sqlserver.lock_released',
        END_MATCHING_COLUMNS = N'resource_0, resource_1, resource_2, transaction_id, database_id',
        RESPOND_TO_MEMORY_PRESSURE = 1
)
WITH
(
    MAX_MEMORY = 8192 KB,
    MAX_DISPATCH_LATENCY = 15 SECONDS
);

若要啟動事件工作階段，請執行下列陳述式：

ALTER EVENT SESSION pair_matching_lock_acquired_released
ON SERVER
STATE = START;

啟動一筆更新T1資料表的交易，但不要提交或復原它。這可確保有取得但未釋放的鎖定。

BEGIN TRANSACTION;
UPDATE T1
    SET id = id + 1;

檢查 SSMS 中事件會話的每個 pair_matching_lock_acquired_released 目標的輸出。

event_counter目標對象的輸出如下，顯示有一個鎖仍未釋放。不過，此目標不會顯示此鎖定的任何詳細資料。

package_name   event_name      count
------------   ----------      -----
sqlserver      lock_acquired   4
sqlserver      lock_released   3

pair_matching目標具有以下輸出結果，已為簡潔起見而截斷。如 event_counter 輸出所建議，我們確實看到了未配對 lock_acquired 事件的那一行資料，以及該事件的更多詳細資訊。

package_name  event_name    timestamp                     associated_object_id  database_id  database_name
------------  ------------  ---------                     -------------         -----------  -------------
sqlserver    lock_acquired   2025-10-01 20:06:07.1890000  1029578706            2            tempdb

請回復交易。

ROLLBACK;

如果您將動作新增至目標所收集的 pair_matching 事件，則也會收集動作資料。例如，您可以在事件中包含動作所提供的 sqlserver.sql_text T-SQL 文字。在此範例中，它會收集取得鎖定的查詢語句。

etw_classic_sync_target 目標

在 SQL Server 中，擴充事件可與 Windows 事件追蹤 (ETW) 搭配運作，用於監視系統活動。如需詳細資訊，請參閱

此 ETW 目標會同步處理其接收的資料。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-10-28

共用方式為

擴充事件目標

event_file 目標

在本機檔案系統中建立具有event_file目標的事件階段作業

在 Azure 儲存體中建立具有event_file目標的事件工作階段

使用受控識別授與存取權

使用共用存取簽章 (Shared Access Signature, SAS) 權杖提供存取權

在 SSMS 中，使用 Azure 儲存體中的事件檔案目標建立事件會話

在 T-SQL 的 Azure 儲存體中建立具有event_file目標的事件工作階段

針對 Azure 儲存體中 event_file 目標的事件會話進行疑難排解

sys.fn_xe_file_target_read_file() 函數

ring_buffer 目標

建立具有「ring_buffer」目標的事件工作階段

event_stream 目標

色階分佈圖目標

建立具有直方圖目標的事件工作階段

event_counter 目標

建立具備事件計數器目標的事件會話

pair_matching 目標

建立具有pair_matching目標的事件工作階段

etw_classic_sync_target 目標

相關內容

意見反應

其他資源