CREATE EVENT SESSION (Transact-SQL)CREATE EVENT SESSION (Transact-SQL)

適用対象:○SQL Server (2008 以降)○Azure SQL Database×Azure SQL Data Warehouse ×Parallel Data Warehouse THIS TOPIC APPLIES TO:yesSQL Server (starting with 2008)yesAzure SQL DatabasenoAzure SQL Data Warehouse noParallel Data Warehouse

イベントのソース、イベント セッション ターゲット、およびイベント セッション オプションを識別する拡張イベント セッションを作成します。Creates an Extended Events session that identifies the source of the events, the event session targets, and the event session options.

トピック リンク アイコン Transact-SQL 構文表記規則Topic link icon Transact-SQL Syntax Conventions.

構文Syntax


CREATE EVENT SESSION event_session_name  
ON SERVER  
{  
    <event_definition> [ ,...n]  
    [ <event_target_definition> [ ,...n] ]  
    [ WITH ( <event_session_options> [ ,...n] ) ]  
}  
;  

<event_definition>::=  
{  
    ADD EVENT [event_module_guid].event_package_name.event_name   
         [ ( {   
                 [ SET { event_customizable_attribute = <value> [ ,...n] } ]  
                 [ ACTION ( { [event_module_guid].event_package_name.action_name [ ,...n] } ) ]  
                 [ WHERE <predicate_expression> ]  
        } ) ]  
}  

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

<event_target_definition>::=  
{  
    ADD TARGET [event_module_guid].event_package_name.target_name  
        [ ( SET { target_parameter_name = <value> [ ,...n] } ) ]  
}  

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

引数Arguments

event_session_nameevent_session_name
イベント セッションのユーザー定義の名前を指定します。Is the user-defined name for the event session. event_session_name には英数字を最大 128 文字まで使用できます。 SQL ServerSQL Server のインスタンス内で一意である必要があり、識別子のルールに従っている必要があります。event_session_name is alphanumeric, can be up to 128 characters, must be unique within an instance of SQL ServerSQL Server, and must comply with the rules for Identifiers.

ADD EVENT [ event_module_guid ].event_package_name.event_nameADD EVENT [ event_module_guid ].event_package_name.event_name
イベント セッションに関連付けるイベントを指定します。Is the event to associate with the event session, where:

  • event_module_guid は、イベントを含むモジュールの GUID です。event_module_guid is the GUID for the module that contains the event.

  • event_package_name は、アクション オブジェクトを含むパッケージです。event_package_name is the package that contains the action object.

  • event_name は、イベント オブジェクトです。event_name is the event object.

    イベントは、object_type 'event' として sys.dm_xe_objects ビューに表示されます。Events appear in the sys.dm_xe_objects view as object_type 'event'.

    SET { event_customizable_attribute= <value> [ ,...n] }SET { event_customizable_attribute= <value> [ ,...n] }
    イベントのカスタマイズ可能な属性を設定できます。Allows customizable attributes for the event to be set. カスタマイズ可能な属性は、column_type 'customizable' および object_name = event_name として sys.dm_xe_object_columns ビューに表示されます。Customizable attributes appear in the sys.dm_xe_object_columns view as column_type 'customizable ' and object_name = event_name.

    ACTION ( { [event_module_guid].event_package_name.action_name [ ,...n] })ACTION ( { [event_module_guid].event_package_name.action_name [ ,...n] })
    イベント セッションに関連付けるアクションを指定します。Is the action to associate with the event session, where:

  • event_module_guid は、イベントを含むモジュールの GUID です。event_module_guid is the GUID for the module that contains the event.

  • event_package_name は、アクション オブジェクトを含むパッケージです。event_package_name is the package that contains the action object.

  • action_name は、アクション オブジェクトです。action_name is the action object.

    アクションは、object_type 'action' として sys.dm_xe_objects ビューに表示されます。Actions appear in the sys.dm_xe_objects view as object_type 'action'.

    WHERE <predicate_expression> イベントを処理する必要があるかどうかを判定するために使用する述語式を指定します。WHERE <predicate_expression> Specifies the predicate expression used to determine if an event should be processed. <predicate_expression> が true の場合、イベントは、セッションのアクションおよびターゲットによって処理されます。If <predicate_expression> is true, the event is processed further by the actions and targets for the session. <predicate_expression> が false の場合、イベントは、セッションのアクションおよびターゲットによって処理される前にセッションによって削除されます。If <predicate_expression> is false, the event is dropped by the session before being processed by the actions and targets for the session. 述語式は 3,000 文字に制限され、これにより文字列引数が制限されます。Predicate expressions are limited to 3000 characters, which limits string arguments.

    event_field_nameevent_field_name
    述語ソースを識別するイベント フィールドの名前を指定します。Is the name of the event field that identifies the predicate source.

    [event_module_guid].event_package_name.predicate_source_name[event_module_guid].event_package_name.predicate_source_name
    グローバル述語ソースの名前を指定します。Is the name of the global predicate source where:

  • event_module_guid は、イベントを含むモジュールの GUID です。event_module_guid is the GUID for the module that contains the event.

  • event_package_name は、述語オブジェクトを含むパッケージです。event_package_name is the package that contains the predicate object.

  • predicate_source_name は、object_type 'pred_source' として sys.dm_xe_objects ビューに定義されます。predicate_source_name is defined in the sys.dm_xe_objects view as object_type 'pred_source'.

    [event_module_guid].event_package_name.predicate_compare_name[event_module_guid].event_package_name.predicate_compare_name
    イベントに関連付ける述語オブジェクトの名前を指定します。Is the name of the predicate object to associate with the event, where:

  • event_module_guid は、イベントを含むモジュールの GUID です。event_module_guid is the GUID for the module that contains the event.

  • event_package_name は、述語オブジェクトを含むパッケージです。event_package_name is the package that contains the predicate object.

  • predicate_compare_name は、object_type 'pred_compare' として sys.dm_xe_objects ビューに定義されるグローバル ソースです。predicate_compare_name is a global source defined in the sys.dm_xe_objects view as object_type 'pred_compare'.

    numbernumber
    decimal を含む任意の数値型です。Is any numeric type including decimal. 制限として、使用可能な物理メモリの不足、または 64 ビット整数として表すのに大きすぎる数字が挙げられます。Limitations are the lack of available physical memory or a number that is too large to be represented as a 64-bit integer.

    'string''string'
    述語の比較に必要な ANSI 文字列または Unicode 文字列です。Either an ANSI or Unicode string as required by the predicate compare. 述語比較関数に対しては、暗黙の文字列型変換は行われません。No implicit string type conversion is performed for the predicate compare functions. 無効な型を渡すとエラーになります。Passing the wrong type results in an error.

    ADD TARGET [event_module_guid].event_package_name.target_nameADD TARGET [event_module_guid].event_package_name.target_name
    イベント セッションに関連付けるターゲットを指定します。Is the target to associate with the event session, where:

  • event_module_guid は、イベントを含むモジュールの GUID です。event_module_guid is the GUID for the module that contains the event.

  • event_package_name は、アクション オブジェクトを含むパッケージです。event_package_name is the package that contains the action object.

  • target_name はターゲットです。target_name is the target. ターゲットは、object_type 'target' として sys.dm_xe_objects ビューに表示されます。Targets appear in sys.dm_xe_objects view as object_type 'target'.

    SET { target_parameter_name= <value> [, ...n] }SET { target_parameter_name= <value> [, ...n] }
    ターゲット パラメーターを設定します。Sets a target parameter. ターゲット パラメーターは、column_type 'customizable' および object_name = target_name として sys.dm_xe_object_columns ビューに表示されます。Target parameters appear in the sys.dm_xe_object_columns view as column_type 'customizable' and object_name = target_name.

重要

リング バッファー ターゲットを使用している場合、max_memory ターゲット パラメーターを 2048 KB に設定し、XML 出力のデータの切り捨てを回避することをお勧めします。If you are using the ring buffer target, we recommend that you set the max_memory target parameter to 2048 kilobytes (KB) to help avoid possible data truncation of the XML output. さまざまなターゲットの種類の使用について詳しくは、「SQL Server 拡張イベント ターゲット」をご覧ください。For more information about when to use the different target types, see SQL Server Extended Events Targets.

WITH ( <event_session_options> [ ,...n] ) イベント セッションで使用するオプションを指定します。WITH ( <event_session_options> [ ,...n] ) Specifies options to use with the event session.

MAX_MEMORY =size [ KB | MB ]MAX_MEMORY =size [ KB | MB ]
イベントのバッファリング用にセッションに割り当てる最大メモリ容量を指定します。Specifies the maximum amount of memory to allocate to the session for event buffering. 既定値は、4 MB です。The default is 4 MB. size は、キロバイト (KB) またはメガバイト (MB) 数を示す整数値です。size is a whole number and can be a kilobyte (KB) or a megabyte (MB) value.

EVENT_RETENTION_MODE = { ALLOW_SINGLE_EVENT_LOSS | ALLOW_MULTIPLE_EVENT_LOSS | NO_EVENT_LOSS }EVENT_RETENTION_MODE = { ALLOW_SINGLE_EVENT_LOSS | ALLOW_MULTIPLE_EVENT_LOSS | NO_EVENT_LOSS }
イベントの削除を処理するために使用するイベント保有モードを指定します。Specifies the event retention mode to use for handling event loss.

ALLOW_SINGLE_EVENT_LOSSALLOW_SINGLE_EVENT_LOSS
セッションから単独のイベントを削除できます。An event can be lost from the session. 単独のイベントは、すべてのイベント バッファーがいっぱいになったときだけ削除されます。A single event is only dropped when all the event buffers are full. イベント バッファーがいっぱいのときに単独のイベントを削除することで、 SQL ServerSQL Server のパフォーマンス特性が許容可能な状態になり、処理後のイベント ストリームのデータ損失を最小限に抑えることができます。Losing a single event when event buffers are full allows for acceptable SQL ServerSQL Server performance characteristics, while minimizing the loss of data in the processed event stream.

ALLOW_MULTIPLE_EVENT_LOSSALLOW_MULTIPLE_EVENT_LOSS
複数のイベントでいっぱいのイベント バッファーをセッションから削除できます。Full event buffers containing multiple events can be lost from the session. 削除されるイベントの数は、セッションに割り当てられているメモリ サイズ、メモリのパーティション分割、およびバッファー内のイベントのサイズによって異なります。The number of events lost is dependant upon the memory size allocated to the session, the partitioning of the memory, and the size of the events in the buffer. このオプションを使用すると、イベント バッファーがすぐにいっぱいになるときにサーバーのパフォーマンスに与える影響を最小限に抑えることができますが、多数のイベントがセッションから削除される可能性があります。This option minimizes performance impact on the server when event buffers are quickly filled, but large numbers of events can be lost from the session.

NO_EVENT_LOSSNO_EVENT_LOSS
イベントの削除は許可されません。No event loss is allowed. このオプションを指定した場合、発生したすべてのイベントが保持されます。This option ensures that all events raised will be retained. このオプションを使用した場合、イベントを開始するすべてのタスクは、イベント バッファーに空きができるまで待機します。Using this option forces all tasks that fire events to wait until space is available in an event buffer. その結果、イベント セッションがアクティブになっている間、検知できる程度のパフォーマンスの問題が発生することがあります。This may cause detectable performance issues while the event session is active. バッファーからイベントがフラッシュされるのを待機する間、ユーザーの接続に遅延が生じる可能性があります。User connections may stall while waiting for events to be flushed from the buffer.

MAX_DISPATCH_LATENCY = { seconds SECONDS | INFINITE }MAX_DISPATCH_LATENCY = { seconds SECONDS | INFINITE }
イベントをイベント セッション ターゲットにディスパッチする前にメモリにバッファリングする時間を指定します。Specifies the amount of time that events will be buffered in memory before being dispatched to event session targets. 既定では、この値は 30 秒に設定されます。By default, this value is set to 30 seconds.

seconds SECONDSseconds SECONDS
ターゲットへのバッファーのフラッシュを開始する前に待つ秒数を指定します。The time, in seconds, to wait before starting to flush buffers to targets. seconds は整数です。seconds is a whole number. 最小待機値は 1 秒です。The minimum latency value is 1 second. ただし、0 を使用すると、INFINITE 待機を指定できます。However, 0 can be used to specify INFINITE latency.

INFINITEINFINITE
バッファーがいっぱいのとき、またはイベント セッションが閉じるときだけ、バッファーをターゲットにフラッシュします。Flush buffers to targets only when the buffers are full, or when the event session closes.

注意

MAX_DISPATCH_LATENCY = 0 SECONDS と MAX_DISPATCH_LATENCY = INFINITE は同じです。MAX_DISPATCH_LATENCY = 0 SECONDS is equivalent to MAX_DISPATCH_LATENCY = INFINITE.

MAX_EVENT_SIZE =size [ KB | MB ]MAX_EVENT_SIZE =size [ KB | MB ]
イベントの最大許容サイズを指定します。Specifies the maximum allowable size for events. MAX_EVENT_SIZE は、MAX_MEMORY よりも大きな単独のイベントを許可するように設定する必要があります。MAX_MEMORY よりも小さな値を設定した場合はエラーが発生します。MAX_EVENT_SIZE should only be set to allow single events larger than MAX_MEMORY; setting it to less than MAX_MEMORY will raise an error. size は、キロバイト (KB) またはメガバイト (MB) 数を示す整数値です。size is a whole number and can be a kilobyte (KB) or a megabyte (MB) value. size をキロバイト単位で指定する場合、最小許容サイズは 64 KB です。If size is specified in kilobytes, the minimum allowable size is 64 KB. MAX_EVENT_SIZE を設定すると、MAX_MEMORY に加えて、サイズが size のバッファーが 2 つ作成されます。When MAX_EVENT_SIZE is set, two buffers of size are created in addition to MAX_MEMORY. つまり、イベントのバッファリングに使用されるメモリの合計量は MAX_MEMORY + 2 * MAX_EVENT_SIZE となります。This means that the total memory used for event buffering is MAX_MEMORY + 2 * MAX_EVENT_SIZE.

MEMORY_PARTITION_MODE = { NONE | PER_NODE | PER_CPU }MEMORY_PARTITION_MODE = { NONE | PER_NODE | PER_CPU }
イベント バッファーを作成する場所を指定します。Specifies the location where event buffers are created.

NONENONE
1 つのバッファー セットが SQL ServerSQL Server インスタンス内に作成されます。A single set of buffers are created within the SQL ServerSQL Server instance.

PER_NODEPER_NODE
NUMA ノードごとに 1 つのバッファー セットが作成されます。A set of buffers are created for each NUMA node.

PER_CPUPER_CPU
CPU ごとに 1 つのバッファー セットが作成されます。A set of buffers are created for each CPU.

TRACK_CAUSALITY = { ON | OFF }TRACK_CAUSALITY = { ON | OFF }
因果関係を追跡するかどうかを指定します。Specifies whether or not causality is tracked. 有効な場合、因果関係により、異なるサーバー接続上の関連イベントを一緒に関連付けることができます。If enabled, causality allows related events on different server connections to be correlated together.

STARTUP_STATE = { ON | OFF }STARTUP_STATE = { ON | OFF }
SQL ServerSQL Server の起動時にこのイベント セッションを自動的に開始するかどうかを指定します。Specifies whether or not to start this event session automatically when SQL ServerSQL Server starts.

注意

STARTUP_STATE = ON の場合、イベント セッションは SQL Server が停止後に再起動されたときにだけ開始されます。If STARTUP_STATE = ON, the event session will only start if SQL Server is stopped and then restarted.

ONON
起動時にイベント セッションが開始されます。The event session is started at startup.

OFFOFF
イベント セッションは起動時に開始されません。The event session is not started at startup.

RemarksRemarks

論理演算子の優先順位は、高い方から NOT、AND、OR です。The order of precedence for the logical operators is NOT (highest), followed by AND, followed by OR.

アクセス許可Permissions

ALTER ANY EVENT SESSION 権限が必要です。Requires the ALTER ANY EVENT SESSION permission.

使用例Examples

test_session という名前のイベント セッションを作成する方法を次の例に示します。The following example shows how to create an event session named test_session. この例では、2 つのイベントを追加し、Event Tracing for Windows ターゲットを使用しています。This example adds two events and uses the Event Tracing for Windows target.

IF EXISTS(SELECT * FROM sys.server_event_sessions WHERE name='test_session')  
    DROP EVENT session test_session ON SERVER;  
GO  
CREATE EVENT SESSION test_session  
ON SERVER  
    ADD EVENT sqlos.async_io_requested,  
    ADD EVENT sqlserver.lock_acquired  
    ADD TARGET package0.etw_classic_sync_target   
        (SET default_etw_session_logfile_path = N'C:\demo\traces\sqletw.etl' )  
    WITH (MAX_MEMORY=4MB, MAX_EVENT_SIZE=4MB);  
GO  

参照See Also

ALTER EVENT SESSION (Transact-SQL) ALTER EVENT SESSION (Transact-SQL)
DROP EVENT SESSION (Transact-SQL) DROP EVENT SESSION (Transact-SQL)
sys.server_event_sessions (Transact-SQL) sys.server_event_sessions (Transact-SQL)
sys.dm_xe_objects (Transact-SQL) sys.dm_xe_objects (Transact-SQL)
sys.dm_xe_object_columns (Transact-SQL)sys.dm_xe_object_columns (Transact-SQL)