變更事件階段作業 （Transact-SQL）

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

啟動或停止事件工作階段，或是變更事件工作階段組態。

Transact-SQL 語法慣例

語法

ALTER EVENT SESSION event_session_name
ON { SERVER | DATABASE }
{
    [ [ {  <add_drop_event> [ , ...n ] }
       | { <add_drop_event_target> [ , ...n ] } ]
    [ WITH ( <event_session_options> [ , ...n ] ) ]
    ]
    | [ STATE = { START | STOP } ]
}

<add_drop_event>::=
{
    [ ADD EVENT <event_specifier>
         [ ( {
                 [ SET { event_customizable_attribute = <value> [ , ...n ] } ]
                 [ ACTION ( { [event_module_guid].event_package_name.action_name [ , ...n ] } ) ]
                 [ WHERE <predicate_expression> ]
        } ) ]
   ]
   | DROP EVENT <event_specifier> }

<event_specifier> ::=
{
[event_module_guid].event_package_name.event_name
}
<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'
}

<add_drop_event_target>::=
{
    ADD TARGET <event_target_specifier>
        [ ( SET { target_parameter_name = <value> [ , ...n ] } ) ]
    | DROP TARGET <event_target_specifier>
}

<event_target_specifier>::=
{
    [event_module_guid].event_package_name.target_name
}

<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

現有事件階段作業的名稱。

狀態 = 開始 |停止

啟動或停止事件工作階段。 STATE引數必須自行指定。 它不能與同一 ALTER EVENT SESSION 陳述中的任何其他參數組合。

新增事件 <event_specifier>

識別要與事件工作階段相關聯的事件。 <event_specifier> 是 [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_specifier>

識別要從事件工作階段中移除的事件。 事件說明符採用 [event_module_guid] 的形式。event_package_name。event_name，其中：

• event_module_guid 為包含此事件之模組的 GUID。

• event_package_name 是包含此動作物件的套件。

• event_name 是事件物件。

  <event_specifier> 必須識別先前新增至事件階段作業的事件。

新增目標 <event_target_specifier>

識別要與事件階段作業相關聯的目標。 事件目標說明符採用 [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_target_specifier>

識別要從事件階段作業中移除的目標。 事件目標說明符採用 [event_module_guid] 的形式。event_package_name。target_name，其中：

• event_module_guid 為包含此事件之模組的 GUID。
• event_package_name 是包含此動作物件的套件。
• target_name 是目標的名稱。

事件目標指定元必須識別先前新增至事件階段作業的目標。

與 （ <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 資料庫 和 Azure SQL 受控執行個體中的事件檔案目標 （使用 SQL Server 2025 或 Always-up-to-date更新原則） ，從 2024 年 6 月開始， NO_EVENT_LOSS 其行為 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 資料庫和 Azure SQL 受控執行個體時移除為支援 EVENT_RETENTION_MODE 的引數。 請避免在新的開發工作中使用此功能，並計劃修改目前使用此功能的應用程式。

MAX_DISPATCH_LATENCY = { 秒 秒 |無限 }

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

• 秒 秒

  將緩衝區排清到目標之前所需等候的時間 (以秒為單位)。 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 = { 開 |關閉 }

指定是否要在資料庫引擎啟動時自動啟動此事件工作階段。

備註

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

• ON

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

• OFF

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

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

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

• 不受限制的

  導致事件階段作業在啟動後無限期執行，直到停止使用 ALTER EVENT SESSION ... STATE = STOP 陳述式為止。

• 持續時間 秒針 |會議記錄 |營業時間 |日

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

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

備註

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

ADD和 DROP 自變數不能用在相同的語句中。

權限

SQL Server 和 Azure SQL 受控執行個體需要 ALTER ANY EVENT SESSION 權限。

Azure SQL 資料庫需要 ALTER ANY DATABASE EVENT SESSION 資料庫中的許可權。

提示

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

範例

A。 啟動和停止事件工作階段

若要將此範例與資料庫事件階段作業搭配使用，請將 取代 ON SERVER 為 ON DATABASE。

ALTER EVENT SESSION test_session ON SERVER STATE = START;
ALTER EVENT SESSION test_session ON SERVER STATE = STOP;

B. 將新事件新增至現有工作階段

若要將此範例與資料庫事件階段作業搭配使用，請將 取代 ON SERVER 為 ON DATABASE。

ALTER EVENT SESSION test_session ON SERVER
ADD EVENT sqlserver.database_transaction_begin,
ADD EVENT sqlserver.database_transaction_end;

C. 檢視工作階段統計資料

若要將此範例與資料庫事件階段作業搭配使用，請將 取代為 sys.dm_xe_sessions，並sys.dm_xe_database_sessions取代sys.dm_xe_session_events為 sys.dm_xe_database_session_events。

SELECT *
FROM sys.dm_xe_sessions
WHERE name = 'test_session';

SELECT se.*
FROM sys.dm_xe_session_events AS se
WHERE EXISTS (SELECT 1
              FROM sys.dm_xe_sessions AS s
              WHERE s.address = se.event_session_address
                    AND s.name = 'test_session');

相關內容

• 建立事件工作階段 （Transact-SQL）
• 掉落活動會話 （Transact-SQL）
• SQL Server 擴充的事件目標
• sys.server_event_sessions （Transact-SQL）
• sys.dm_xe_objects （Transact-SQL）
• sys.dm_xe_object_columns （Transact-SQL）