ALTER EVENT SESSION (Transact-SQL)

適用対象:SQL ServerAzure SQL Managed Instance

イベント セッションの開始および停止、またはイベント セッションの構成変更を行います。

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 = START |止める

イベント セッションを開始または停止します。 STATE引数は、単独で指定する必要があります。 同じ ALTER EVENT SESSION ステートメント内の他の引数と組み合わせることはできません。

ADD EVENT <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 = <value> [ ,...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;

ACTION ( { [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;

WHERE <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 ビット整数として表すことができる任意の数値型。

'string'

述語比較子で必要な ANSI または Unicode 文字列。 述語比較関数に対しては、暗黙の文字列型変換は行われません。 予期しない型の値を渡すと、エラーが発生します。

DROP EVENT <event_specifier>

イベント セッションから削除するイベントを識別します。 イベント指定子は [event_module_guid] の形式です。event_package_name。event_name。次の場所:

• event_module_guid は、イベントを含むモジュールの GUID です。

• event_package_name は、アクション オブジェクトを含むパッケージです。

• event_name は、イベント オブジェクトです。

  <event_specifier> は、以前にイベント セッションに追加されたイベントを識別する必要があります。

ADD TARGET <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;

イベント セッションには、0 個、1 個、または多数の ターゲットを含めることができます。 イベント セッションに追加されるすべてのターゲットは異なる必要があります。 たとえば、event_file ターゲットが既にあるセッションに 2 つ目のevent_file ターゲットを追加することはできません。

一般的に使用されるターゲットの使用例など、詳細については、「 拡張イベント ターゲット」を参照してください。

SET { target_parameter_name = <value> [ , ...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';

ターゲットの種類の詳細については、「 拡張イベント ターゲット」を参照してください。

DROP TARGET <event_target_specifier>

イベント セッションから削除するターゲットを識別します。 イベント ターゲット指定子は [event_module_guid] の形式です。event_package_name。target_name。次の場所:

• event_module_guid は、イベントを含むモジュールの GUID です。
• event_package_name は、アクション オブジェクトを含むパッケージです。
• target_name はターゲットの名前です。

イベント ターゲット指定子は、以前にイベント セッションに追加されたターゲットを識別する必要があります。

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

  セッションからイベントを削除できます。 単独のイベントは、すべてのイベント バッファーがいっぱいになった場合にのみ削除されます。 イベント バッファーがいっぱいになったときに 1 つのイベントを失うと、パフォーマンスへの影響が最小限に抑えられ、処理されたイベント ストリーム内のデータの損失も最小限に抑えられます。

• ALLOW_MULTIPLE_EVENT_LOSS

  複数のイベントでいっぱいのイベント バッファーをセッションから削除できます。 削除されるイベントの数は、セッションに割り当てられているメモリ サイズ、メモリのパーティション分割、バッファー内のイベントのサイズによって異なります。 通常、このオプションを使用すると、イベント バッファーがすぐに満たされるが、セッションから大量のイベントが失われる可能性がある場合に、サーバーに対するパフォーマンスへの影響を回避できます。

• NO_EVENT_LOSS

  イベントの削除は許可されません。 このオプションにより、発生したすべてのイベントが保持されます。 このオプションを使用した場合、イベントを開始するすべてのタスクは、イベント バッファーに空きができるまで待機します。 NO_EVENT_LOSSを使用すると、イベント セッションがアクティブな間に検出可能なパフォーマンスの問題が発生する可能性があります。 ユーザー セッションとクエリは、バッファーからイベントがフラッシュされるのを待っている間にストールする可能性があります。

  注

  2024 年 6 月以降、Azure SQL Database および Azure SQL Managed Instance ( SQL Server 2025 または Always-up-to-date更新ポリシーを使用) のイベント ファイル ターゲットの場合、 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 Database と Azure SQL Managed Instance に対する今後の更新でサポートされる EVENT_RETENTION_MODE 引数として削除される予定です。 新しい開発作業ではこの機能を使用しないでください。現在この機能を使用しているアプリケーションを変更することを計画してください。

MAX_DISPATCH_LATENCY = { seconds SECONDS |INFINITE }

イベントをイベント セッション ターゲットにディスパッチする前にメモリにバッファリングする時間を指定します。 既定では、この値は 30 秒に設定されます。

• お代わり お代わり

  ターゲットへのバッファーのフラッシュを開始する前に待つ秒数を指定します。 seconds は整数です。 最小待機値は 1 秒です。 ただし、0 を使用すると、INFINITE 待機を指定できます。

• 無限

  バッファーがいっぱいになっている、またはイベント セッションが閉じられる場合にのみ、バッファーをターゲットにフラッシュします。

MAX_EVENT_SIZE = size [ KB |MB ]

イベントの最大許容サイズを指定します。 MAX_EVENT_SIZEは、MAX_MEMORYより大きい 1 つのイベントのみを許可するように設定する必要があります。をMAX_MEMORY未満に設定すると、エラーが発生します。 size は、キロバイト (KB) またはメガバイト (MB) 数を示す整数値です。 size をキロバイト単位で指定する場合、最小許容サイズは 64 KB です。 MAX_EVENT_SIZEを設定すると、MAX_MEMORYに加えて size の 2 つのバッファーが作成され、イベント バッファリングに使用されるメモリの合計が MAX_MEMORY + 2 * MAX_EVENT_SIZE。

MEMORY_PARTITION_MODE = { NONE |PER_NODE |PER_CPU }

イベント バッファーのアフィニティを指定します。 NONE以外のオプションバッファーが増え、メモリ消費量が増加しますが、競合を回避し、大規模なマシンのパフォーマンスを向上させることができます。

• なし

  データベース エンジン インスタンス内に 1 つのバッファー セットが作成されます。

• PER_NODE

  各 NUMA ノードに対して一連のバッファーが作成されます。

• PER_CPU

  CPU ごとにバッファーのセットが作成されます。

TRACK_CAUSALITY = { ON |OFF }

イベントの因果関係を追跡するかどうかを指定します。 有効な場合、因果関係により、異なるサーバー接続上の関連イベントを一緒に関連付けることができます。

STARTUP_STATE = { ON |OFF }

データベース エンジンの起動時にこのイベント セッションを自動的に開始するかどうかを指定します。

• オン

  イベント セッションは起動時に開始されます。

• OFF

  イベント セッションは起動時に開始されません。

MAX_DURATION = { time duration { SECONDS |MINUTES |HOURS |DAYS } |UNLIMITED }

適用対象: SQL Server 2025 (17.x) プレビュー

• 無制限の

  ALTER EVENT SESSION ... STATE = STOP ステートメントを使用して停止するまで、開始後にイベント セッションを無期限に実行します。

• 期間 SECONDS |MINUTES |HOURS |日

  セッション開始後に指定した時間が経過すると、イベント セッションが自動的に停止します。 サポートされる最大期間は、2,147,483 秒、35,792 分、596 時間、または 24 日間です。

詳細については、「 タイム バインド イベント セッション」を参照してください。

解説

イベント セッション引数の詳細については、「 拡張イベント セッション」を参照してください。

ADD引数とDROP引数を同じステートメントで使用することはできません。

アクセス許可

SQL Server と Azure SQL Managed Instance には、 ALTER ANY EVENT SESSION アクセス許可が必要です。

Azure SQL Database には、データベースの ALTER ANY DATABASE EVENT SESSION アクセス許可が必要です。

例

Ａ。 イベント セッションの開始と停止

この例をデータベース イベント セッションで使用するには、 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)
• DROP EVENT SESSION (Transact-SQL)
• SQL Server 拡張イベント ターゲット
• sys.server_event_sessions (Transact-SQL)
• sys.dm_xe_objects (Transact-SQL)
• sys.dm_xe_object_columns (Transact-SQL)