建立事件工作階段（Transact-SQL）

適用於：SQL Server Azure SQL Database Azure SQL Managed Instance Microsoft Fabric 中的 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 } ]
    [ [ , ] MAX_DURATION = { <time duration> { SECONDS | MINUTES | HOURS | DAYS } | UNLIMITED } ]
}

引數

event_session_name

事件階段作業的使用者定義名稱。 event_session_name 是英數字元，最多可以有 128 個字元，在 SQL Server 執行個體中必須是唯一的，而且必須符合資料庫識別碼的規則。

在 { 服務器上 |資料庫 }

判斷事件階段作業是否在伺服器或資料庫的內容中。

Azure SQL Database 與 Microsoft Fabric 中的 SQL 資料庫需要 DATABASE。

新增事件 [event_module_guid]。event_package_name。event_name

要與事件工作階段相關聯的事件，其中：

event_module_guid 為包含此事件之模組的 GUID。
event_package_name 是包含事件的套件。
event_name 是事件名稱。

您可以透過執行下列查詢來找到可用的事件：

SELECT o.name AS event_name,
       o.description AS event_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'event'
ORDER BY event_name ASC;

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

事件的可自訂屬性。

您可以執行下列查詢來找到指定事件的可自訂屬性：

SELECT object_name,
       name AS column_name,
       type_name,
       column_value,
       description
FROM sys.dm_xe_object_columns
WHERE object_name = 'event-name-placeholder'
      AND column_type = 'customizable'
ORDER BY column_name ASC;

動作（ { [event_module_guid]。event_package_name。action_name [ ,...n ] }）

與事件相關聯的動作，其中：

event_module_guid 是包含動作之模組的 GUID。
event_package_name 是包含動作的套件。
action_name 是動作的名稱。

您可以透過執行下列查詢來找到可用的動作：

SELECT o.name AS action_name,
       o.description AS action_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'action'
ORDER BY action_name ASC;

哪裡predicate_expression <>

指定用來判斷是否應該處理事件的述詞運算式。如果 <predicate_expression> 為 true，則工作階段的動作與目標會進一步處理此事件。如果 <predicate_expression> 為 false，則會卸除事件，避免其他動作和目標處理。每個述詞運算式限制為 3,000 個字元。

event_field_name

識別述詞來源的事件欄位名稱。

您可以執行下列查詢來找到事件的欄位：

SELECT oc.name AS field_name,
       oc.type_name AS field_type,
       oc.description AS field_description
FROM sys.dm_xe_objects AS o
INNER JOIN sys.dm_xe_packages AS p
ON o.package_guid = p.guid
INNER JOIN sys.dm_xe_object_columns AS oc
ON o.name = oc.object_name
   AND
   o.package_guid = oc.object_package_guid
WHERE o.object_type = 'event'
      AND
      o.name = 'event-name-placeholder'
      AND
      oc.column_type = 'data'
ORDER BY field_name ASC;

[event_module_guid]。event_package_name。predicate_source_name

廣域述詞來源的名稱，其中：

event_module_guid 為包含此事件之模組的 GUID。
event_package_name 是包含述詞來源物件的套件。
predicate_source_name 是述詞來源的名稱。

述詞來源可以透過執行下列查詢來找到：

SELECT o.name AS predicate_source_name,
       o.description AS predicate_source_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'pred_source'
ORDER BY predicate_source ASC;

[event_module_guid].event_package_name.predicate_compare_name

述詞比較器物件的名稱，其中：

event_module_guid 為包含此事件之模組的 GUID。
event_package_name 是包含述詞比較器物件的套件。
predicate_compare_name 是述詞比較子名稱。

述詞比較器可以透過執行下列查詢來找到：

SELECT o.name AS predicate_comparator_name,
       o.description AS predicate_comparator_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'pred_compare'
ORDER BY predicate_comparator ASC;

數字

任何可以表示為 64 位整數的數值類型。

'字串'

述詞比較器所需的 ANSI 或 Unicode 字串。不會針對述詞比較函數執行隱含字串類型轉換。傳遞非預期類型的值會導致錯誤。

新增目標 [event_module_guid]。event_package_name。target_name

是要與事件工作階段產生關聯的目標，其中：

event_module_guid 是包含目標之模組的 GUID。
event_package_name 是包含目標的套件。
target_name 是目標名稱。

您可以執行下列查詢來找到可用的目標：

SELECT o.name AS target_name,
       o.description AS target_description,
       o.capabilities_desc,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'target'
ORDER BY target_name ASC;

事件階段作業可以有零個、一個或多個目標。新增至事件工作階段的所有目標都必須不同。例如，您無法將第二個 event_file 目標新增至已具有 event_file 目標的工作階段。

如需詳細資訊，包括常用目標的使用範例，請參閱擴充事件目標。

SET { target_parameter_name = <值> [ ， ...n ] }

設定目標參數。

若要查看所有目標參數及其描述，請執行下列查詢，並取代 target-name-placeholder 為目標名稱，例如 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-placeholder';

重要

如果您使用環形緩衝區目標，建議您將MAX_MEMORY參數（與工作階段參數不同MAX_MEMORY）設定為 1,024 KB 或更少，以協助避免 XML 輸出可能的資料截斷。

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

與（ <event_session_options> [ ,...n ] ）

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

MAX_MEMORY = 大小 [ 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

事件可能會從工作階段遺失。當所有事件緩衝區已滿時，只會卸除單一事件。當事件緩衝區已滿時遺失單一事件，可將效能影響降到最低，同時將已處理事件串流中資料的遺失降到最低。
ALLOW_MULTIPLE_EVENT_LOSS

包含多個事件的完整事件緩衝區可能會從工作階段中遺失。遺失的事件數目取決於配置給工作階段的記憶體大小、記憶體的分割及緩衝區中的事件大小。此選項通常會避免在事件緩衝區快速填滿時對伺服器造成效能影響，但階段作業可能會遺失大量事件。
NO_EVENT_LOSS

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

注意

對於 Azure SQL 資料庫、Microsoft Fabric 中的 SQL 資料庫，以及 Azure SQL Managed Instance（採用 SQL Server 2025 或 Always-up-to-date更新政策）中的事件檔案目標，從 2024 NO_EVENT_LOSS 年 6 月開始，行為與 ALLOW_SINGLE_EVENT_LOSS. 如果您指定 NO_EVENT_LOSS，則會傳回訊息 ID 25665、嚴重性 10 且訊息 This target doesn't support the NO_EVENT_LOSS event retention mode. The ALLOW_SINGLE_EVENT_LOSS retention mode is used instead. 的警告，並建立階段作業。

這項變更可避免連線逾時、容錯移轉延遲，以及與 Azure Blob 儲存體中的事件檔案目標搭配使用時 NO_EVENT_LOSS 可能降低資料庫可用性的其他問題。

NO_EVENT_LOSS 計劃在未來更新 Azure SQL Database、Microsoft Fabric 中的 SQL 資料庫及 Azure SQL Managed Instance 時，作為支援 EVENT_RETENTION_MODE 參數被移除。請避免在新的開發工作中使用這項功能，並規劃修改目前使用這項功能的應用程式。

MAX_DISPATCH_LATENCY = { 秒秒 |無限 }

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

秒SECONDS

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

只有當緩衝區已滿，或是當事件工作階段關閉時，才能將緩衝區排清到目標。

MAX_EVENT_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 = { 無 |PER_NODE |PER_CPU }

指定事件緩衝區的親和性。以外的 NONE 選項會導致更多緩衝區和更高的記憶體耗用量，但可以避免爭用並改善較大電腦上的效能。

沒有

會在資料庫引擎執行個體內建立一組緩衝區。
PER_NODE

會為每個 NUMA 節點建立一組緩衝區。
PER_CPU

系統會為每個 CPU 建立一組緩衝區。

TRACK_CAUSALITY = { 開 |關閉 }

指定是否要追蹤因果。如果啟用的話，因果可允許不同伺服器連接上的相關事件彼此相互關聯。

STARTUP_STATE = { 開 |關閉 }

指定當 SQL Server 啟動時，是否要自動啟動這個事件工作階段。

注意

如果，事件 STARTUP_STATE = ON工作階段會在資料庫引擎停止然後重新啟動時啟動。若要立即啟動事件階段作業，請使用 ALTER EVENT SESSION ... ON SERVER STATE = START。

ON

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

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

MAX_DURATION = { 持續時間 { 秒 |會議記錄 |營業時間 |天數 } |無限 }

適用於：SQL Server 2025 （17.x）

不受限制的

建立事件階段作業，一旦啟動，該階段作業就會無限期執行，直到停止使用陳述式為 ALTER EVENT SESSION ... STATE = STOP 止。這是預設 MAX_DURATION 值 if 未指定。
持續時間 秒針 |會議記錄 |營業時間 |日

建立事件階段作業，該階段作業會在階段作業啟動後經過指定的時間後自動停止。支援的持續時間上限為 2,147,483 秒或 35,792 分鐘，或 596 小時或 24 天。

如需詳細資訊，請參閱時間限制事件工作階段。

備註

如需事件工作階段引數的詳細資訊，請參閱擴充事件工作階段。

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

權限

SQL Server 和 Azure SQL 受控執行個體需要 CREATE ANY EVENT SESSION （在 SQL Server 2022 中引進）或 ALTER ANY EVENT SESSION 許可權。

Azure SQL 資料庫和 Microsoft Fabric 中的 SQL 資料庫需要資料庫中的 CREATE ANY DATABASE EVENT SESSION 權限。

提示

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

範例

A。 SQL Server 和 Azure SQL 受控執行個體範例

以下範例將示範如何建立名為 test_session 的事件工作階段。此範例新增兩個事件並使用 event_file 目標，將每個檔案的大小限制為 256 MB，並將保留的檔案數目限制為 10。

IF EXISTS (SELECT 1
           FROM sys.server_event_sessions
           WHERE name = 'test_session')
    DROP EVENT SESSION test_session ON SERVER;

CREATE EVENT SESSION test_session ON SERVER
ADD EVENT sqlserver.rpc_starting,
ADD EVENT sqlserver.sql_batch_starting,
ADD EVENT sqlserver.error_reported
ADD TARGET package0.event_file
    (
    SET filename = N'C:\xe\test_session.xel',
        max_file_size = 256,
        max_rollover_files = 10
    )
WITH (MAX_MEMORY = 4 MB);

B. Azure SQL 資料庫範例

範例逐步解說，請檢閱在 Azure 儲存體中建立具有event_file目標的事件工作階段，以及在記憶體中建立具有ring_buffer目標的事件工作階段。

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

針對 SQL Server 撰寫的某些 Transact-SQL 程式碼範例需要小的變更，才能在 Azure SQL 資料庫或 Fabric 中的 SQL 資料庫中執行。這類程式碼範例的其中一個類別涉及目錄檢視，其名稱前置詞視乎資料庫引擎類型而有所差異：

server_ - 適用於 SQL Server 和 Azure SQL 受控執行個體的前置詞
database_ - Azure SQL 資料庫、Fabric 中的 SQL 資料庫和 SQL 受控執行個體的前置詞

Azure SQL 資料庫和 Fabric 中的 SQL 資料庫僅支援資料庫範圍的事件工作階段。 SQL Server Management Studio（SSMS）支援 Azure SQL 資料庫的資料庫範圍事件會話：在物件總管中，每個資料庫下方都會出現包含資料庫範圍的擴充事件節點。

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

注意

建議針對 Azure SQL 受控執行個體使用伺服器範圍的事件工作階段。

資料庫範圍的事件工作階段不會顯示在適用於 Azure SQL 受控執行個體的 SSMS 的物件總管中。在 SQL 受控執行個體上，資料庫範圍的事件工作階段只能使用 Transact-SQL 來查詢和管理。

為了示範，下表列出並比較兩個目錄檢視子集。由於子集支援兩種不同的資料庫引擎類型，因此具有不同的名稱前置詞。

SQL Server 和 Azure SQL 受控執行個體中的名稱	Azure SQL 資料庫、Fabric 中的 SQL 資料庫和 Azure SQL 受控執行個體中的名稱
`sys.server_event_session_actions` `sys.server_event_session_events` `sys.server_event_session_fields` `sys.server_event_session_targets` `sys.server_event_sessions`	`sys.database_event_session_actions` `sys.database_event_session_events` `sys.database_event_session_fields` `sys.database_event_session_targets` `sys.database_event_sessions`

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-11-19