CREATE EVENT SESSION (Transact-SQL)

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

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

Transact-SQL 構文表記規則

構文

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

引数

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

ターゲットの種類の詳細については、「 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 を指定すると、バッファーがいっぱいになったか、イベント セッションが閉じられた場合にのみ、バッファーをターゲットにフラッシュします。

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

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

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

解説

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

アクセス許可

SQL Server と SQL Managed Instance では、 CREATE ANY EVENT SESSION (SQL Server 2022 で導入) または 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 に対してサーバー スコープのセッションを完全にサポートしています。すべてのサーバー スコープのセッションを含む拡張イベント ノードが、オブジェクト エクスプローラー内の各マネージド インスタンスの [管理] フォルダーの下に表示されます。

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

上記の表の 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;

関連項目

• sys.server_event_sessions (Transact-SQL)
• sys.dm_xe_objects (Transact-SQL)
• sys.dm_xe_object_columns (Transact-SQL)

次のステップ

• ALTER EVENT SESSION (Transact-SQL)
• DROP EVENT SESSION (Transact-SQL)