CREATE EVENT SESSION (Transact-SQL)

[アーティクル]
02/01/2024

適用対象:SQL Server Azure SQL Database Azure SQL Managed Instance

イベントのソース、イベントセッションターゲット、およびイベントセッションオプションを識別する拡張イベントセッションを作成します。

構文

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

Note

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

引数

event_session_name

イベントセッションのユーザー定義の名前を指定します。 event_session_name には英数字を最大 128 文字まで使用できます。SQL Server のインスタンス内で一意である必要があり、識別子のルールに従っている必要があります。

ADD EVENT [ 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 ビューに定義されます。

number は、decimal を含む任意の数値型です。制限として、使用可能な物理メモリの不足、または 64 ビット整数として表すのに大きすぎる数字が挙げられます。

'string' は、述語の比較に必要な ANSI または Unicode 文字列です。述語比較関数に対しては、暗黙の文字列型変換は行われません。無効な型を渡すとエラーになります。

ADD TARGET [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] }

ターゲットパラメーターを設定します。

すべてのターゲットパラメーターとその説明を表示するには、次のクエリを実行し、プレースホルダーを target-name ターゲット名に置き換えます (例: event_file, ring_buffer, など histogram)。

SELECT name AS target_parameter_name,
       column_value AS default_value,
       description
FROM sys.dm_xe_object_columns
WHERE column_type = 'customizable'
      AND
      object_name = 'target-name';

重要

リングバッファーターゲットを使用している場合は、XML 出力のデータ切り捨てが発生しないように、ターゲット パラメーター (セッションパラメーターとはMAX_MEMORY異なる) を 1024 KB (KB (キロバイト)) 以下に設定MAX_MEMORYすることをお勧めします。

ターゲットの種類の詳細については、「SQL Server の拡張イベントのターゲット」を参照してください。

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

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

MAX_MEMORY =size [ KB | MB ]

イベントのバッファリング用にセッションに割り当てる最大メモリ容量を指定します。既定値は 4 MB です。size は、キロバイト (KB) またはメガバイト (MB) を示す整数値です。最大量は 2 GB (2,048 MB (メガバイト) 未満) を超えることはできません。ただし、GB 範囲のメモリ値を使用することはお勧めしません。

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 を指定した場合、イベントの削除は許可されません。このオプションにより、発生したすべてのイベントが保持されます。このオプションを使用した場合、イベントを開始するすべてのタスクは、イベントバッファーに空きができるまで待機します。 NO_EVENT_LOSSを使用すると、イベントセッションがアクティブな間に検出可能なパフォーマンスの問題が発生する可能性があります。バッファーからイベントがフラッシュされるのを待機する間、ユーザーの接続に遅延が生じる可能性があります。

MAX_DISPATCH_LATENCY = { seconds SECONDS | INFINITE }

イベントをイベントセッションターゲットにディスパッチする前にメモリにバッファリングする時間を指定します。既定では、この値は 30 秒に設定されます。

seconds SECONDS によって、ターゲットへのバッファーのフラッシュを開始する前に待機する秒数を指定できます。 seconds は整数です。最小待機値は 1 秒です。ただし、0 を使用すると、INFINITE 待機を指定できます。

INFINITE を指定すると、バッファーがいっぱいになったか、イベントセッションが閉じられた場合にのみ、バッファーをターゲットにフラッシュします。

Note

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に加えてサイズの 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 の起動時にこのイベントセッションを自動的に開始するかどうかを指定します。

Note

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

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

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

解説

論理演算子の優先順位は、高い方から NOT、AND、OR です。

アクセス許可

SQL Server と SQL Managed Instance では、ALTER ANY EVENT SESSION アクセス許可が必要です。 SQL Database では、データベースにおける ALTER ANY DATABASE EVENT SESSION アクセス許可が必要です。

例

SQL Server の例

test_session という名前のイベントセッションを作成する方法を次の例に示します。この例では、2 つのイベントを追加し、Event Tracing for Windows ターゲットを使用しています。

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

Azure SQL の例

Azure SQL Managed Instance または Azure SQL Database で、.xel ファイルを Azure Blob Storage に格納します。 sys.fn_xe_file_target_read_file を使用して、自分で作成した拡張イベントセッションから読み取り、Azure Blob Storage に格納できます。例のチュートリアルについては、Azure SQL Database および Azure SQL Managed Instance の拡張イベントのためのイベントファイルターゲットコードに関する記事を参照してください。

コード例は、Azure SQL Database と SQL Managed Instance で異なる場合があります

SQL Server 向けに作成された一部の Transact-SQL コード例は、Azure で実行する場合は少し変更する必要があります。このようなコード例のカテゴリの 1 つに、データベースエンジンの種類によって名前プレフィックスが異なるカタログビューが含まれます。

server_ - SQL Server および Azure SQL Managed Instance のプレフィックス
database_ - Azure SQL Database および SQL Managed Instance のプレフィックス

Azure SQL Database では、データベーススコープのイベントセッションのみがサポートされています。 SQL Server Management Studio (SSMS) では、Azure SQL Database のデータベーススコープのセッションが完全にサポートされます。データベーススコープのイベントセッションを含む拡張イベント ノードが、オブジェクトエクスプローラーの各データベースの下に表示されます。

Azure SQL Managed Instance では、データベーススコープのセッションとサーバースコープのセッションの両方がサポートされます。 SSMS は、SQL Managed Instance に対してサーバースコープのセッションを完全にサポートしています。すべてのサーバースコープのセッションを含む拡張イベント ノードが、オブジェクトエクスプローラー内の各マネージドインスタンスの [管理] フォルダーの下に表示されます。

Note

マネージドインスタンスには、サーバースコープのセッションをお勧めします。データベーススコープのセッションは、Azure SQL Managed Instance での SSMS のオブジェクトエクスプローラーには表示されません。データベーススコープのセッションは、マネージドインスタンスを使用する場合にのみ、Transact-SQL を使用してクエリの実行と管理を行うことができます。

説明のために、次の表に、カタログビューの 2 つのサブセットの比較リストを示します。簡潔にするために、サブセットは、文字列 _event も含むビュー名に限定されています。サポートする異なるデータベースエンジンタイプが異なるため、サブセットの名前のプレフィックスは異なります。

SQL Server と Azure SQL Managed Instance の名前	Azure SQL Database と Azure SQL Managed Instance の名前
server_event_notifications server_event_session_actions server_event_session_events server_event_session_fields server_event_session_targets server_event_sessions server_events server_trigger_events	database_event_session_actions database_event_session_events database_event_session_fields database_event_session_targets database_event_sessions

上記の表の 2 つのリストは、2022 年 3 月時点のものです。最新の一覧を表示するには、次の Transact-SQL SELECT ステートメントを実行します。

SELECT name
    FROM sys.all_objects
    WHERE
        (name LIKE 'database[_]%' OR
         name LIKE 'server[_]%' )
        AND name LIKE '%[_]event%'
        AND type = 'V'
        AND SCHEMA_NAME(schema_id) = 'sys'
    ORDER BY name;

CREATE EVENT SESSION (Transact-SQL)

構文

引数

event_session_name

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>

ADD TARGET [event_module_guid].event_package_name.target_name

SET { target_parameter_name= <value> [, ...n] }

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

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 の例

Azure SQL の例

コード例は、Azure SQL Database と SQL Managed Instance で異なる場合があります

関連項目

次のステップ

フィードバック

フィードバック

その他のリソース