ALTER EVENT SESSION (Transact-SQL)
イベント セッションの開始および停止、またはイベント セッションの構成変更を行います。
.gif "トピック リンク アイコン")
構文
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 |
イベント パッケージ内のイベントを指定します。
イベントは、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]} ) |
イベント セッションに関連付けるアクションを指定します。
アクションは、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].event_package_name.predicate_compare_name |
イベントに関連付ける述語オブジェクトの名前を指定します。
|
||||||||
DROP EVENT <event_specifier> |
<event_specifier> で識別されるイベントを削除します。 <event_specifier> は、イベント セッションで有効である必要があります。 |
||||||||
ADD TARGET <event_target_specifier> |
<event_target_specifier>で識別されるターゲットをイベント セッションに関連付けます。 |
||||||||
[event_module_guid].event_package_name.target_name |
イベント セッションのターゲットの名前を指定します。ただし、
|
||||||||
SET { target_parameter_name = <value> [, ...n]} |
ターゲット パラメーターを設定します。 ターゲット パラメーターは、column_type 'customizable' および object_name = target_name として sys.dm_xe_object_columns ビューに表示されます。
|
||||||||
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 } |
イベントの削除を処理するために使用するイベント保有モードを指定します。
|
||||||||
MAX_DISPATCH_LATENCY = { seconds SECONDS | INFINITE } |
イベントをイベント セッション ターゲットにディスパッチする前にメモリにバッファリングする時間を指定します。 最小待機値は 1 秒です。 ただし、0 を使用すると、INFINITE 待機を指定できます。 既定では、この値は 30 秒に設定されます。
|
||||||||
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 } |
イベント バッファーを作成する場所を指定します。
|
||||||||
TRACK_CAUSALITY = { ON | OFF } |
因果関係を追跡するかどうかを指定します。 有効な場合、因果関係により、異なるサーバー接続上の関連イベントを一緒に関連付けることができます。 |
||||||||
STARTUP_STATE = { ON | OFF } |
SQL Server の起動時にこのイベント セッションを自動的に開始するかどうかを指定します。
|
.gif "重要な注意事項")
重要.gif "注意")
注説明
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)
sys.server_event_sessions (Transact-SQL)
sys.dm_xe_objects (Transact-SQL)
sys.dm_xe_object_columns (Transact-SQL)