次の方法で共有

ALTER EVENT SESSION (Transact-SQL)

  • [アーティクル]

適用対象: SQL Server Azure SQL Managed Instance

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

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 } ]  
}

引数

期間 定義
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 ビューに表示されます。

注: リング バッファー ターゲットを使用する場合は、XML 出力のデータ切り捨てが発生しないように、max_memoryターゲット パラメーターを 2,048 KB (KB) に設定することをお勧めします。 さまざまなターゲットの種類の使用について詳しくは、「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
イベントの削除は許可されません。 このオプションにより、発生したすべてのイベントが保持されます。 このオプションを使用した場合、イベントを開始するすべてのタスクは、イベント バッファーに空きができるまで待機します。 その結果、イベント セッションがアクティブになっている間、検知できる程度のパフォーマンスの問題が発生することがあります。 バッファーからイベントがフラッシュされるのを待機する間、ユーザーの接続に遅延が生じる可能性があります。 Azure SQL Database のイベント ファイル ターゲットの場合、ALLOW_SINGLE_EVENT_LOSSと同じように動作します。 詳細については、「 EVENT_RETENTION_MODE」を参照してください。
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より大きい 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 つのバッファー セットが 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 アクセス許可が必要です。

ヒント

SQL Server 2022 では、拡張イベントに対してより詳細なアクセス許可が多数導入されました。詳細については、「 Blog: PoLP への準拠を向上させるために SQL Server 2022 と Azure SQL の新しい詳細なアクセス許可を参照してください。

例

次の例では、イベント セッションを開始し、いくつかのライブ セッション統計を取得します。次に、既存のセッションに 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

関連項目