CREATE EVENT SESSION (Transact-SQL)

2025-09-03

適用対象: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 } ]
    [ [ , ] MAX_DURATION = { <time duration> { SECONDS | MINUTES | HOURS | DAYS } | UNLIMITED } ]
}

引数

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 はイベント名です。

使用可能なイベントは、次のクエリを実行して見つけることができます。

SELECT o.name AS event_name,
       o.description AS event_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'event'
ORDER BY event_name ASC;

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

イベントのカスタマイズ可能な属性。

特定のイベントのカスタマイズ可能な属性は、次のクエリを実行することで見つけることができます。

SELECT object_name,
       name AS column_name,
       type_name,
       column_value,
       description
FROM sys.dm_xe_object_columns
WHERE object_name = 'event-name-placeholder'
      AND column_type = 'customizable'
ORDER BY column_name ASC;

ACTION ( { [event_module_guid]。event_package_name。action_name [ ,...n ] })

イベントに関連付けるアクション。次の場所があります。

event_module_guid は、アクションを含むモジュールの GUID です。
event_package_name アクションを含むパッケージです。
action_name はアクションの名前です。

使用可能なアクションは、次のクエリを実行することで確認できます。

SELECT o.name AS action_name,
       o.description AS action_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'action'
ORDER BY action_name ASC;

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 は述語ソースの名前です。

述語ソースは、次のクエリを実行して見つけることができます。

SELECT o.name AS predicate_source_name,
       o.description AS predicate_source_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'pred_source'
ORDER BY predicate_source ASC;

[event_module_guid].event_package_name.predicate_compare_name

述語比較子オブジェクトの名前。ここで次のようになります。

event_module_guid は、イベントを含むモジュールの GUID です。
event_package_name は、述語比較子オブジェクトを含むパッケージです。
predicate_compare_name 述語比較子名です。

述語比較子は、次のクエリを実行して見つけることができます。

SELECT o.name AS predicate_comparator_name,
       o.description AS predicate_comparator_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'pred_compare'
ORDER BY predicate_comparator ASC;

番号

64 ビット整数として表すことができる任意の数値型。

'string'

述語比較子で必要な ANSI または Unicode 文字列。述語比較関数に対しては、暗黙の文字列型変換は行われません。予期しない型の値を渡すと、エラーが発生します。

ADD TARGET [event_module_guid]。event_package_name。target_name

イベントセッションに関連付けるターゲットを指定します。

event_module_guid は、ターゲットを含むモジュールの GUID です。
event_package_name は、ターゲットを含むパッケージです。
target_name はターゲット名です。

使用可能なターゲットは、次のクエリを実行して見つけることができます。

SELECT o.name AS target_name,
       o.description AS target_description,
       o.capabilities_desc,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'target'
ORDER BY target_name ASC;

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

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

すべてのターゲットパラメーターとその説明を表示するには、次のクエリを実行し、 target-name-placeholder をターゲット名 ( 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-placeholder';

重要

リングバッファーターゲットを使用している場合は、XML 出力のデータ切り捨てを回避するために、 MAX_MEMORYtarget パラメーター ( MAX_MEMORYsession パラメーターとは異なる) を 1,024 KB 以下に設定することをお勧めします。

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

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

セッションからイベントを削除できます。単独のイベントは、すべてのイベントバッファーがいっぱいになった場合にのみ削除されます。イベントバッファーがいっぱいになったときに 1 つのイベントを失うと、パフォーマンスへの影響が最小限に抑えられ、処理されたイベントストリーム内のデータの損失も最小限に抑えられます。
ALLOW_MULTIPLE_EVENT_LOSS

複数のイベントでいっぱいのイベントバッファーをセッションから削除できます。削除されるイベントの数は、セッションに割り当てられているメモリサイズ、メモリのパーティション分割、バッファー内のイベントのサイズによって異なります。通常、このオプションを使用すると、イベントバッファーがすぐに満たされるが、セッションから大量のイベントが失われる可能性がある場合に、サーバーに対するパフォーマンスへの影響を回避できます。
NO_EVENT_LOSS

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

Note

2024 年 6 月以降、always-up-to-date 更新ポリシーを使用する Azure SQL Database および Azure SQL Managed Instance のイベントファイルターゲットの場合、NO_EVENT_LOSSはLOW_SINGLE_EVENT_LOSSと同じように動作します。 NO_EVENT_LOSS、メッセージ ID 25665、重大度 10、およびメッセージを含む警告を指定した場合、 このターゲットはNO_EVENT_LOSSイベント保持モードをサポートしていません。代わりに、ALLOW_SINGLE_EVENT_LOSS保持モードが使用されます。 が返され、セッションが作成されます。

この変更により、接続のタイムアウト、フェールオーバーの遅延、およびその他の問題が回避され、Azure BLOB ストレージのイベントファイルターゲットでNO_EVENT_LOSSを使用すると、データベースの可用性が低下する可能性があります。

NO_EVENT_LOSSは、Azure SQL Database と Azure SQL Managed Instance に対する今後の更新でサポートされるEVENT_RETENTION_MODE引数として削除される予定です。新規の開発作業ではこの機能を使用しないようにし、現在この機能を使用しているアプリケーションは修正することを検討してください。

MAX_DISPATCH_LATENCY = { seconds SECONDS |INFINITE }

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

お代わりSECONDS

ターゲットへのバッファーのフラッシュを開始する前に待つ秒数を指定します。 seconds は整数です。最小待機値は 1 秒です。ただし、0 を使用すると、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 つのバッファーセットが作成されます。
PER_NODE

各 NUMA ノードに対して一連のバッファーが作成されます。
PER_CPU

CPU ごとにバッファーのセットが作成されます。

TRACK_CAUSALITY = { ON |OFF }

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

STARTUP_STATE = { ON |OFF }

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

Note

STARTUP_STATE = ON場合、データベースエンジンが停止してから再起動されたときにイベントセッションが開始されます。イベントセッションをすぐに開始するには、 ALTER EVENT SESSION ... ON SERVER STATE = STARTを使用します。

オン

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

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

MAX_DURATION = { time duration { SECONDS |MINUTES |HOURS |DAYS } |UNLIMITED }

適用対象: SQL Server 2025 (17.x) プレビュー

無制限の

ALTER EVENT SESSION ... STATE = STOP ステートメントを使用して停止するまで、開始されると無期限に実行されるイベントセッションを作成します。これは、 MAX_DURATION が指定されていない場合の既定値です。
期間 SECONDS |MINUTES |HOURS |日

セッション開始後に指定した時間が経過した後に自動的に停止するイベントセッションを作成します。サポートされる最大期間は、2,147,483 秒、35,792 分、596 時間、または 24 日間です。

詳細については、「タイムバインドイベントセッション」を参照してください。

解説

イベントセッション引数の詳細については、「拡張イベントセッション」を参照してください。

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

アクセス許可

SQL Server と Azure SQL Managed Instance には、 CREATE ANY EVENT SESSION (SQL Server 2022 で導入)、または ALTER ANY EVENT SESSION アクセス許可が必要です。

Azure SQL Database には、データベースの CREATE ANY DATABASE EVENT SESSION アクセス許可が必要です。

ヒント

SQL Server 2022 では、拡張イベントに対するより詳細なアクセス許可が導入されました。詳細については、「ブログ: PoLP への準拠を向上させるための SQL Server 2022 と Azure SQL の新しい詳細なアクセス許可」を参照してください。

例

Ａ。 SQL Server と Azure SQL Managed Instance の例

test_session という名前のイベントセッションを作成する方法を次の例に示します。この例では、2 つのイベントを追加し、 event_file ターゲットを使用して、各ファイルのサイズを 256 MB に制限し、保持されるファイル数を 10 に制限します。

IF EXISTS (SELECT 1
           FROM sys.server_event_sessions
           WHERE name = 'test_session')
    DROP EVENT SESSION test_session ON SERVER;

CREATE EVENT SESSION test_session ON SERVER
ADD EVENT sqlserver.rpc_starting,
ADD EVENT sqlserver.sql_batch_starting,
ADD EVENT sqlserver.error_reported
ADD TARGET package0.event_file
    (
    SET filename = N'C:\xe\test_session.xel',
        max_file_size = 256,
        max_rollover_files = 10
    )
WITH (MAX_MEMORY = 4 MB);

B: Azure SQL Database の例

チュートリアルの例については、「 Azure Storage でevent_file ターゲットを持つイベントセッションを作成する」を参照し、メモリ内にring_buffer ターゲットを含むイベントセッションを作成します。

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

SQL Server 用に記述された Transact-SQL コード例の中には、Azure SQL Database または Azure SQL Managed Instance で実行するために小さな変更が必要なものもあります。このようなコード例のカテゴリの 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 に対してサーバースコープのセッションを完全にサポートしています。すべてのサーバースコープのセッションを含む拡張イベント ノードが、オブジェクトエクスプローラー内の各マネージドインスタンスの [管理] フォルダーの下に表示されます。