• [アーティクル]

ALTER EVENT SESSION (Transact-SQL)

イベント セッションを開始または停止したり、イベント セッションの構成を変更したりします。

トピック リンク アイコン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 ビューに表示されます。

重要な注意事項重要
リング バッファー ターゲットを使用している場合、max_memory ターゲット パラメーターを 2048 KB に設定し、XML 出力のデータの切り捨てを回避することをお勧めします。異なるターゲットの種類を使用する場合の詳細については、「SQL Server 拡張イベント ターゲット」を参照してください。

DROP TARGET <event_target_specifier>

<event_target_specifier> によって識別されるターゲットを削除します。<event_target_specifier> は、イベント セッションで有効である必要があります。

WITH ( <event_session_options> [ ,...n])

イベント セッションで使用するオプションを指定します。

MAX_MEMORY= size [ KB | MB ]

イベントのバッファリング用にセッションに割り当てる最大メモリ容量を指定します。既定値は 4 MB です。size は、キロバイト (KB) またはメガバイト (MB) 数を示す整数値です。非同期ターゲット用に割り当てられたメモリは、この値とは区別されます。

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_NODENUMA ノードごとに 1 つのバッファー セットが作成されます。詳細については、「Non-Uniform Memory Access について」を参照してください。
PER_CPUCPU ごとに 1 つのバッファー セットが作成されます。

TRACK_CAUSALITY ={ ON | OFF }

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

STARTUP_STATE ={ ON | OFF }

SQL Server の起動時にこのイベント セッションを自動的に開始するかどうかを指定します。

注意注
STARTUP_STATE = ON の場合、イベント セッションは SQL Server が停止後に再起動されたときにだけ開始されます。
用語定義
ON起動時にイベント セッションが開始されます。
OFFイベント セッションは起動時に開始されません。

説明

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

権限

CONTROL SERVER 権限が必要です。

使用例

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