ALTER EVENT SESSION (Transact-SQL)

適用対象: はいSQL Server (サポートされているすべてのバージョン)

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

トピック リンク アイコン Transact-SQL 構文表記規則

構文

ALTER EVENT SESSION event_session_name  
ON SERVER  
{  
    [ [ {  <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 } ]  
}  

注意

SQL Server 2014 以前の Transact-SQL 構文を確認するには、以前のバージョンのドキュメントを参照してください。

引数

用語 定義
event_session_name 既存のイベント セッションの名前です。
STATE = START | STOP イベント セッションを開始または停止します。 この引数は、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 は、イベント オブジェクトです。

イベントは、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 は、object_type 'pred_source' として sys.dm_xe_objects ビューに定義されます。
[event_module_guid].event_package_name.predicate_compare_name 以下の場合、イベントに関連付ける述語オブジェクトの名前です。

- event_module_guid は、イベントを含むモジュールの GUID です。
- event_package_name は、述語オブジェクトを含むパッケージです。
- predicate_compare_name は、object_type 'pred_compare' として sys.dm_xe_objects ビューに定義されるグローバル ソースです。
DROP EVENT <event_specifier> <event_specifier> で識別されるイベントを削除します。 <event_specifier> は、イベント セッションで有効である必要があります。
ADD TARGET <event_target_specifier> <event_target_specifier> で識別されるターゲットをイベント セッションに関連付けます。
[event_module_guid].event_package_name.target_name 以下の場合、イベント セッションのターゲットの名前です。

- event_module_guid は、イベントを含むモジュールの GUID です。
- event_package_name は、アクション オブジェクトを含むパッケージです。
- target_name はアクションです。 アクションは、object_type 'target' として sys.dm_xe_objects ビューに表示されます。
SET { target_parameter_name= <value> [, ...n] } ターゲット パラメーターを設定します。 ターゲット パラメーターは、column_type 'customizable' および object_name = target_name として sys.dm_xe_object_columns ビューに表示されます。

注: リング バッファー ターゲットを使用している場合、max_memory ターゲット パラメーターを 2048 KB に設定し、XML 出力のデータの切り捨てを回避することをお勧めします。 さまざまなターゲットの種類の使用について詳しくは、「SQL Server 拡張イベント ターゲット」をご覧ください。
DROP TARGET <event_target_specifier> <event_target_specifier> で識別されるターゲットを削除します。 <event_target_specifier> は、イベント セッションで有効である必要があります。
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
イベントの削除は許可されません。 このオプションを指定した場合、発生したすべてのイベントが保持されます。 このオプションを使用した場合、イベントを開始するすべてのタスクは、イベント バッファーに空きができるまで待機します。 その結果、イベント セッションがアクティブになっている間、検知できる程度のパフォーマンスの問題が発生することがあります。 バッファーからイベントがフラッシュされるのを待機する間、ユーザーの接続に遅延が生じる可能性があります。
MAX_DISPATCH_LATENCY = { seconds SECONDS | INFINITE } イベントをイベント セッション ターゲットにディスパッチする前にメモリにバッファリングする時間を指定します。 最小待機値は 1 秒です。 ただし、0 を使用すると、INFINITE 待機を指定できます。 既定では、この値は 30 秒に設定されます。

seconds SECONDS
ターゲットへのバッファーのフラッシュを開始する前に待つ秒数を指定します。 seconds は整数です。

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 をキロバイト単位で指定する場合、最小許容サイズは 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 つのバッファー セットが SQL Server インスタンス内で作成されます。

PER NODE - NUMA ノードごとに 1 つのバッファー セットが作成されます。

PER CPU - CPU ごとに 1 つのバッファー セットが作成されます。
TRACK_CAUSALITY = { ON | OFF } 因果関係を追跡するかどうかを指定します。 有効な場合、因果関係により、異なるサーバー接続上の関連イベントを一緒に関連付けることができます。
STARTUP_STATE = { ON | OFF } SQL Server の起動時にこのイベント セッションを自動的に開始するかどうかを指定します。

STARTUP_STATE=ON の場合、イベント セッションは SQL Server が停止後に再起動されたときにだけ開始されます。

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

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

解説

ADD 引数と DROP 引数は同じステートメントで一緒に使用できません。

アクセス許可

ALTER ANY EVENT SESSION アクセス許可が必要です。

次の例では、イベント セッションを開始し、いくつかのライブ セッション統計を取得します。次に、既存のセッションに 2 つのイベントを追加します。

-- Start the event session  
ALTER EVENT SESSION test_session ON SERVER  
STATE = start;  
GO  

-- Obtain live session statistics   
SELECT * FROM sys.dm_xe_sessions;  
SELECT * FROM sys.dm_xe_session_events;  
GO  
  
-- Add new events to the session  
ALTER EVENT SESSION test_session ON SERVER  
ADD EVENT sqlserver.database_transaction_begin,  
ADD EVENT sqlserver.database_transaction_end;  
GO  

参照

CREATE EVENT 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)