拡張イベントのターゲット

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

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

この記事では、拡張イベントターゲットを使用するタイミングと方法について説明します。各ターゲットについて次のことを説明します。

イベントによって送信されるデータを収集およびレポートするの機能。
パラメータ、説明が不要なパラメータの場合を除きます

次の表では、異なるデータベースエンジンにおける各ターゲットの種類の可用性について説明します。

ターゲットの型	SQL Server	Azure SQL Database	Azure SQL Managed Instance
etw_classic_sync_target	はい	いいえ	いいえ
event_counter	はい	イエス	はい
event_file	はい	イエス	はい
event_stream	はい	イエス	はい
histogram	はい	イエス	はい
pair_matching	はい	いいえ	いいえ
ring_buffer	はい	イエス	はい

前提条件

この記事を最大限に活用するには、次の操作を行う必要があります。

「クイックスタート: の拡張イベント」で説明されている拡張イベントの基本について理解していること。
SQL Server Management Studio (SSMS) ユーティリティの最近のバージョンをインストールしてあること。詳細については、「 Download SQL Server Management Studio (SSMS)」 (SQL Server Management Studio (SSMS) のダウンロード) を参照してください。
SSMS のオブジェクトエクスプローラーでイベントセッションのターゲットノードを右クリックして出力データを簡単に表示する方法を知っていること。

パラメーター、アクション、フィールド

拡張イベントの中心になるのは CREATE EVENT SESSION ステートメントです。ステートメントを記述するには、次のものが必要です。

セッションに追加するイベント
それぞれの選択したイベントに関連付けられているフィールド。
セッションに追加する各ターゲットに関連付けられているパラメーター

システムビューからこのようなリストを返す SELECT ステートメントは、次の記事のセクション C からコピーできます。

SQL Server の拡張イベントに対するシステムビューからの SELECT と JOIN
- C.4 : イベントに対する SELECT のフィールド。
- C.6 : ターゲットに対する SELECT のパラメーター。
- C.3 : SELECT のアクション。

実際 CREATE EVENT SESSION のステートメントのコンテキストで使用されるパラメーター、フィールド、およびアクションは、セクション B2 (T-SQL の観点) から確認できます。

etw_classic_sync_target ターゲット

SQL Server の拡張イベントは、Windows イベントトレーシング(ETW) と連携してシステムの使用状況を監視できます。詳細については、以下を参照してください:

この ETW ターゲットは受信したデータを 同期的 に処理しますが、ほとんどのターゲットは 非同期的に処理します。

Note

Azure SQL Managed Instance および Azure SQL Database では、etw_classic_sync_target ターゲットはサポートされていません。別の方法として、Azure Storage に event_file 格納されている BLOB でターゲットを使用します。

event_counter ターゲット

event_counter ターゲットを使うと、特定のイベントが発生した回数をカウントできます。

他のほとんどのターゲットとは次の点が異なります。

ターゲットには event_counter パラメーターがありません。
event_counter ターゲットは、受信したデータを 同期的に処理します。

event_counter 目標によってキャプチャされる出力の例

package_name   event_name         count
------------   ----------         -----
sqlserver      checkpoint_begin   4

次に、前の CREATE EVENT SESSION 結果を返したステートメントを示します。この例では、カウントが package0.counter 4 に達した後にカウントを停止するために、WHERE 句述語でフィールドを使用しました。

CREATE EVENT SESSION [event_counter_1]
    ON SERVER
    ADD EVENT sqlserver.checkpoint_begin   -- Test by issuing CHECKPOINT; statements.
    (
        WHERE [package0].[counter] <= 4   -- A predicate filter.
    )
    ADD TARGET package0.event_counter
    WITH
    (
        MAX_MEMORY = 4096 KB,
        MAX_DISPATCH_LATENCY = 3 SECONDS
    );

event_file ターゲット

event_file ターゲットは、バッファーからディスクファイルまたは Azure Storage 内の BLOB にイベントセッション出力を書き込みます。

filename 句で ADD TARGET パラメーターを指定します。ファイル名の拡張子は xel にする必要があります。
指定したファイル名をプレフィックスとして使用し、その後に日時に基づく長い整数と、xel 拡張子が付加されます。

Note

Azure SQL Managed Instance と Azure SQL Database は、filename パラメーターの値として Azure Storage 内の BLOB のみ。

特に SQL Database (または SQL Managed Instance) の event_file コード例については、「SQL Database の拡張イベント用のイベントファイルターゲットコード」に関するページを参照してください。

CREATE EVENT SESSION と event_file ターゲット

ADD TARGET ターゲットを追加する event_file 句の CREATE EVENT SESSION 例を次に示します。

CREATE EVENT SESSION [locks_acq_rel_eventfile_22]
    ON SERVER
    ADD EVENT sqlserver.lock_acquired
    (
        SET
            collect_database_name=(1),
            collect_resource_description=(1)
        ACTION (sqlserver.sql_text,sqlserver.transaction_id)
        WHERE
        (
            [database_name]=N'InMemTest2'
            AND
            [object_id]=370100359
        )
    ),
    ADD EVENT sqlserver.lock_released
    (
        SET
            collect_database_name=1,
            collect_resource_description=1
        ACTION(sqlserver.sql_text,sqlserver.transaction_id)
        WHERE
        (
            [database_name]=N'InMemTest2'
            AND
            [object_id]=370100359
        )
    )
    ADD TARGET package0.event_counter,
    ADD TARGET package0.event_file
    (
        SET filename=N'C:\temp\locks_acq_rel_eventfile_22-.xel'
    )
    WITH
    (
        MAX_MEMORY=4096 KB,
        MAX_DISPATCH_LATENCY=10 SECONDS
    );

sys.fn_xe_file_target_read_file() 関数

event_file ターゲットは、人間が読むことのできないバイナリ形式で、受信したデータを格納します。 sys.fn_xe_file_target_read_file関数を使用すると、ファイルの内容を xel リレーショナル行セットとして表すことができます。

SQL Server 2016 以降のバージョンでは、次の例のような SELECT ステートメントを使用します。

SELECT f.*
--,CAST(f.event_data AS XML)  AS [Event-Data-Cast-To-XML]  -- Optional
FROM sys.fn_xe_file_target_read_file(
    'C:\temp\locks_acq_rel_eventfile_22-*.xel', NULL, NULL, NULL)  AS f;

SQL Server 2014 の場合は、次の例のようなSELECT ステートメントを使用します。 SQL Server 2014 以降では、xem ファイルは使われなくなっています。

SELECT f.*
--,CAST(f.event_data AS XML)  AS [Event-Data-Cast-To-XML]  -- Optional
FROM sys.fn_xe_file_target_read_file(
    'C:\temp\locks_acq_rel_eventfile_22-*.xel', 'C:\temp\metafile.xem', NULL, NULL) AS f;

どちらの例でも、* ワイルドカードは、指定したプレフィックスで始まるすべての xel ファイルを読み取るために使用されます。

Azure SQL Database では、sys.fn_xe_file_target_read_file() BLOB を含むコンテナーに対する List アクセス許可を持つ Read SAS トークンを含むデータベーススコープの資格情報を作成した後、xel 関数を呼び出すことができます。

/*
Create a master key to protect the secret of the credential
*/
IF NOT EXISTS (
    SELECT 1
    FROM sys.symmetric_keys
    WHERE name = '##MS_DatabaseMasterKey##'
)
CREATE MASTER KEY;

/*
(Re-)create a database scoped credential.
The name of the credential must match the URI of the blob container.
*/
IF EXISTS (
    SELECT *
    FROM sys.database_credentials
    WHERE name = 'https://exampleaccount4xe.blob.core.windows.net/extended-events-container'
)
DROP DATABASE SCOPED CREDENTIAL [https://exampleaccount4xe.blob.core.windows.net/extended-events-container];

/*
The secret is the SAS token for the container. The Read and List permissions are set.
*/
CREATE DATABASE SCOPED CREDENTIAL [https://exampleaccount4xe.blob.core.windows.net/extended-events-container]
    WITH IDENTITY = 'SHARED ACCESS SIGNATURE',
        SECRET = 'sp=rl&st=2023-10-09T22:12:54Z&se=2023-10-10T06:12:54Z&spr=https&sv=2022-11-02&sr=c&sig=REDACTED';

/*
Return event session data
*/
SELECT f.*
--,CAST(f.event_data AS XML)  AS [Event-Data-Cast-To-XML]  -- Optional
FROM sys.fn_xe_file_target_read_file('https://exampleaccount4xe.blob.core.windows.net/extended-events-container/event-session-1', DEFAULT, DEFAULT, DEFAULT) AS f;

Azure SQL Managed Instance では、xelBLOB を含むコンテナーに対するsys.fn_xe_file_target_read_file()アクセス許可を持つRead SAS トークンを含むサーバー資格情報を作成した後で、List関数を呼び出すことができます。

IF NOT EXISTS (
    SELECT 1
    FROM sys.symmetric_keys
    WHERE name = '##MS_DatabaseMasterKey##'
)
CREATE MASTER KEY ENCRYPTION BY PASSWORD = 'REDACTED';

/*
(Re-)create a database scoped credential.
The name of the credential must match the URI of the blob container.
*/
IF EXISTS (
    SELECT *
    FROM sys.credentials
    WHERE name = 'https://exampleaccount4xe.blob.core.windows.net/extended-events-container'
)
DROP CREDENTIAL [https://exampleaccount4xe.blob.core.windows.net/extended-events-container];

/*
The secret is the SAS token for the container. The Read and List permissions are set.
*/
CREATE CREDENTIAL [https://exampleaccount4xe.blob.core.windows.net/extended-events-container]
    WITH IDENTITY = 'SHARED ACCESS SIGNATURE',
        SECRET = 'sp=rl&st=2023-10-09T22:12:54Z&se=2023-10-10T06:12:54Z&spr=https&sv=2022-11-02&sr=c&sig=REDACTED';

/*
Return event session data
*/
SELECT f.*
--,CAST(f.event_data AS XML)  AS [Event-Data-Cast-To-XML]  -- Optional
FROM sys.fn_xe_file_target_read_file('https://exampleaccount4xe.blob.core.windows.net/extended-events-container/event-session-1', DEFAULT, DEFAULT, DEFAULT) AS f;

ヒント

最初の引数に完全な BLOB 名の代わりに BLOB 名プレフィックスを指定すると、sys.fn_xe_file_target_read_file() 関数はプレフィックスに一致するコンテナー内のすべての BLOB からデータを返します。これにより、Azure Storage ではサポートされていない * ワイルドカードを使用せずに、特定のイベントセッションのすべてのロールオーバーファイルからデータを取得できます。

前の Azure SQL の例では、xel 名前付きセッションのすべてのロールオーバーファイルを読み取る event-session-1 拡張機能を省略しています。

event_file ターゲットに格納されているデータ

これは、SQL Server 2016 (13.x) 以降の sys.fn_xe_file_target_read_file バージョンから返されるデータの例です。

module_guid                            package_guid                           object_name     event_data                                                                                                                                                                                                                                                                                          file_name                                                      file_offset
-----------                            ------------                           -----------     ----------                                                                                                                                                                                                                                                                                          ---------                                                      -----------
D5149520-6282-11DE-8A39-0800200C9A66   03FDA7D0-91BA-45F8-9875-8B6DD0B8E9F2   lock_acquired   <event name="lock_acquired" package="sqlserver" timestamp="2016-08-07T20:13:35.827Z"><action name="transaction_id" package="sqlserver"><value>39194</value></action><action name="sql_text" package="sqlserver"><value><![CDATA[  select top 1 * from dbo.T_Target;  ]]></value></action></event>   C:\temp\locks_acq_rel_eventfile_22-_0_131150744126230000.xel   11776
D5149520-6282-11DE-8A39-0800200C9A66   03FDA7D0-91BA-45F8-9875-8B6DD0B8E9F2   lock_released   <event name="lock_released" package="sqlserver" timestamp="2016-08-07T20:13:35.832Z"><action name="transaction_id" package="sqlserver"><value>39194</value></action><action name="sql_text" package="sqlserver"><value><![CDATA[  select top 1 * from dbo.T_Target;  ]]></value></action></event>   C:\temp\locks_acq_rel_eventfile_22-_0_131150744126230000.xel   11776

histogram ターゲット

histogram ターゲットができるのは

複数の項目の発生を個別にカウントすることです。
異なる種類の項目の発生をカウントする。
- [Event fields] (イベントのフィールド)
- アクション

histogram ターゲットは、受信したデータを 同期的に処理します。

source_type パラメーターは、ヒストグラムターゲットを制御するためのキーです。

イベントフィールドのデータを source_type=0 収集します。
アクションのデータを source_type=1 収集します。これが既定です。

slots パラメーターの既定値は 256 です。別の値を割り当てると、値は次の 2 の累乗に切り上げられます。たとえば、slots=59 は 64 まで切り上げられます。 histogram ターゲットのヒストグラムスロットの最大数は 16384 です。

ターゲットとして histogram コマンドを使うときに、予期しない結果が表示されることがあります。一部のイベントは予想されるスロットに表示されない場合があります。一方、他のスロットでは、イベントの数が予想よりも多い場合があります。

これは、スロットにイベントを割り当てるときにハッシュ競合が発生した場合に発生する可能性があります。これはまれですが、ハッシュ競合が発生した場合、あるスロットでカウントする必要があるイベントが別のスロットでカウントされます。このため、特定のスロットの数が 0 と表示されるだけでイベントが発生しなかった場合は注意が必要です。

ここでは、次のシナリオを例に説明します。

histogram ターゲットとしてヒストグラムを使用し、ごとにグループ化して拡張イベントセッションを設定し、ストアドプロシージャの実行を object_id 収集します。
ストアドプロシージャ A を実行してから、ストアドプロシージャ B を実行します。

両方の object_id ストアドプロシージャのハッシュ関数が同じ値を返した場合、ヒストグラムはストアドプロシージャ A が 2 回実行されていることを示し、ストアドプロシージャ B は表示されません。

個別の値の数が比較的少ない場合にこの問題を軽減するには、ヒストグラムスロットの数を予想される個別の値の二乗よりも大きく設定します。たとえば、histogram ターゲットが source イベントフィールドに table_name 設定されていて、データベースに 20 個のテーブルがある場合、20*20 = 400 になります。 400 を超える 2 の次の累乗は 512 です。これは、この例で推奨されるスロット数です。

アクションを含むヒストグラムターゲット

その ADD TARGET ... (SET ...) 句では、次 CREATE EVENT SESSION のステートメントでターゲットパラメーターの割り当て source_type=1 を指定します。これは、ヒストグラムターゲットがアクションを追跡することを意味します。

この例では、ADD EVENT ... (ACTION ...) 句は sqlos.system_thread_id というターゲットの 1 つのアクションだけを提供します。この ADD TARGET ... (SET ...) 句では、source=N'sqlos.system_thread_id' 割り当てが表示されます。

Note

イベントセッションごとに同じ型の複数のターゲットを追加することはできません。これには histogram ターゲットが含まれます。また、histogram ターゲットごとに複数のソース (アクションまたはイベントフィールド) を含めることはできません。そのため、histogram 別個のターゲットで追加のアクション (またはイベント) フィールドを追跡するには、新しいイベントセッションが必要です。

CREATE EVENT SESSION [histogram_lockacquired]
    ON SERVER
    ADD EVENT sqlserver.lock_acquired
        (
        ACTION
            (
            sqlos.system_thread_id
            )
        )
    ADD TARGET package0.histogram
        (
        SET
            filtering_event_name=N'sqlserver.lock_acquired',
            slots=16,
            source=N'sqlos.system_thread_id',
            source_type=1
        );

キャプチャされたデータを次に示します。 value 列の system_thread_id 値は値です。たとえば、全部で 236 個のロックがスレッド 6540 で取得されました。

value   count
-----   -----
 6540     236
 9308      91
 9668      74
10144      49
 5244      44
 2396      28

使用可能なアクションを検出するための SELECT

C.3 の SELECT ステートメントは、CREATE EVENT SESSION ステートメントで指定できるシステムが提供するアクションを取得できます。 WHERE 句で、o.name LIKE フィルターを編集して目的のアクションを指定します。

C.3 の SELECT で返される行セットの例を次に示します。 system_thread_id アクションは 2 行目にあります。

Package-Name   Action-Name                 Action-Description
------------   -----------                 ------------------
package0       collect_current_thread_id   Collect the current Windows thread ID
sqlos          system_thread_id            Collect current system thread ID
sqlserver      create_dump_all_threads     Create mini dump including all threads
sqlserver      create_dump_single_thread   Create mini dump for the current thread

イベントフィールドを含むヒストグラムターゲット

次の例では、source_type=0が設定されます。 source に割り当てられる値はイベントフィールドです。

CREATE EVENT SESSION [histogram_checkpoint_dbid]
    ON SERVER
    ADD EVENT  sqlserver.checkpoint_begin
    ADD TARGET package0.histogram
    (
    SET
        filtering_event_name = N'sqlserver.checkpoint_begin',
        source               = N'database_id',
        source_type          = 0
    );

histogram ターゲットでは次のようなデータがキャプチャされます。このデータは、ID=5 のデータベースで checkpoint_begin イベントが 7 回発生したことを示しています。

value   count
-----   -----
5       7
7       4
6       3

選択したイベントで使用可能なフィールドを検出する SELECT

C.4 SELECT のステートメントでは、選択できるイベントフィールドが示されます。最初に、o.name LIKE フィルターを編集して選択するイベント名を指定します。

C.4 SELECT からは次のような行セットが返されます。この行セットでは、checkpoint_begin イベントが histogram ターゲットに提供できるフィールドは database_id の 1 つのみであることがわかります。

Package-Name   Event-Name         Field-Name   Field-Description
------------   ----------         ----------   -----------------
sqlserver      checkpoint_begin   database_id  NULL
sqlserver      checkpoint_end     database_id  NULL

pair_matching ターゲット

pair_matching ターゲットを使用すると、対応する終了イベントのない開始イベントを検出できます。たとえば、lock_acquired イベントが発生した後に適切なタイミングで対応する lock_released イベントが発生しないと、問題になる可能性があります。

システムで開始イベントと終了イベントが自動的にマッチングされることはありません。代わりに、開発者が CREATE EVENT SESSION ステートメントでシステムにマッチングを示す必要があります。開始イベントと終了イベントがマッチングする場合、ペアは破棄されるので、マッチングしていない開始イベントに注目できます。

開始イベントと終了イベントのペアのマッチングが可能なフィールドの検索

C.4 SELECT を使用することで、次の行セットには lock_acquired イベントの対象になるフィールドが約 16 個あることがわかります。ここで示されている行セットは、マッチングするフィールドがわかるように手動で分割されています。 duration などの一部のフィールドでは、照合を試みるのは無意味です。

Package-Name   Event-Name   Field-Name               Field-Description
------------   ----------   ----------               -----------------
sqlserver   lock_acquired   database_name            NULL
sqlserver   lock_acquired   mode                     NULL
sqlserver   lock_acquired   resource_0               The ID of the locked object, when lock_resource_type is OBJECT.
sqlserver   lock_acquired   resource_1               NULL
sqlserver   lock_acquired   resource_2               The ID of the lock partition, when lock_resource_type is OBJECT, and resource_1 is 0.
sqlserver   lock_acquired   transaction_id           NULL

sqlserver   lock_acquired   associated_object_id     The ID of the object that requested the lock that was acquired.
sqlserver   lock_acquired   database_id              NULL
sqlserver   lock_acquired   duration                 The time (in microseconds) between when the lock was requested and when it was canceled.
sqlserver   lock_acquired   lockspace_nest_id        NULL
sqlserver   lock_acquired   lockspace_sub_id         NULL
sqlserver   lock_acquired   lockspace_workspace_id   NULL
sqlserver   lock_acquired   object_id                The ID of the locked object, when lock_resource_type is OBJECT. For other lock resource types it will be 0
sqlserver   lock_acquired   owner_type               NULL
sqlserver   lock_acquired   resource_description     The description of the lock resource. The description depends on the type of lock. This is the same value as the resource_description column in the sys.dm_tran_locks view.
sqlserver   lock_acquired   resource_type            NULL

pair_matching ターゲットの例

次の CREATE EVENT SESSION ステートメントでは、2 つのイベントと 2 つのターゲットが指定されています。 pair_matching ターゲットでは、イベントをペアにするために 2 つのフィールドセットが指定されています。 begin_matching_columns に割り当てられたコンマ区切りフィールドのシーケンスと end_matching_columns は同じである必要があります。コンマ区切り値で示されるフィールドの間にタブや改行文字があってはなりませんが、スペースは許されます。

結果を絞り込むため、最初に sys.objects からテストテーブルの object_id を検索して選択しました。 ADD EVENT ... (WHERE ...) 句にその 1 つのオブジェクト ID のフィルターを追加しました。

CREATE EVENT SESSION [pair_matching_lock_a_r_33]
    ON SERVER
    ADD EVENT sqlserver.lock_acquired
    (
        SET
            collect_database_name = 1,
            collect_resource_description = 1
        ACTION (sqlserver.transaction_id)
        WHERE
        (
            [database_name] = 'InMemTest2'
            AND
            [object_id] = 370100359
        )
    ),
    ADD EVENT sqlserver.lock_released
    (
        SET
            collect_database_name = 1,
            collect_resource_description = 1
        ACTION (sqlserver.transaction_id)
        WHERE
        (
            [database_name] = 'InMemTest2'
            AND
            [object_id] = 370100359
        )
    )
    ADD TARGET package0.event_counter,
    ADD TARGET package0.pair_matching
    (
        SET
            begin_event = N'sqlserver.lock_acquired',
            begin_matching_columns =
                N'resource_0, resource_1, resource_2, transaction_id, database_id',
            end_event = N'sqlserver.lock_released',
            end_matching_columns =
                N'resource_0, resource_1, resource_2, transaction_id, database_id',
            respond_to_memory_pressure = 1
    )
    WITH
    (
        MAX_MEMORY = 8192 KB,
        MAX_DISPATCH_LATENCY = 15 SECONDS
    );

イベントセッションをテストするため、意図的に、取得した 2 つのロックが解放されないようにしています。次のような T-SQL 手順を使用しました。

BEGIN TRANSACTION.
UPDATE MyTable....
ターゲットを調べるまで、意図的に aCOMMIT TRANSACTION を発行しません。
後でテストした後、COMMIT TRANSACTION を発行しました。

簡単な event_counter ターゲットでは次のような出力行が得られました。 52-50=2 であるため、この出力からは、pair-matching ターゲットからの出力を調べるときにペアになっていない 2 つの lock_acquired イベントが表示されることになります。

package_name   event_name      count
------------   ----------      -----
sqlserver      lock_acquired   52
sqlserver      lock_released   50

pair_matching の出力は次のとおりです。 event_counter 出力で提案されているように、2 つの lock_acquired 行が実際に表示されます。これら 2 つの lock_acquired イベントはペアになっていません。

package_name   event_name      timestamp                     database_name   duration   mode   object_id   owner_type   resource_0   resource_1   resource_2   resource_description   resource_type   transaction_id
------------   ----------      ---------                     -------------   --------   ----   ---------   ----------   ----------   ----------   ----------   --------------------   -------------   --------------
sqlserver      lock_acquired   2016-08-05 12:45:47.9980000   InMemTest2      0          S      370100359   Transaction  370100359    3            0            [INDEX_OPERATION]      OBJECT          34126
sqlserver      lock_acquired   2016-08-05 12:45:47.9980000   InMemTest2      0          IX     370100359   Transaction  370100359    0            0                                   OBJECT          34126

ペアになっていない lock_acquired イベントの行には、sqlserver.sql_text アクションによって提供される T-SQL テキストを含めることができます。これにより、ロックを取得したクエリがキャプチャされます。

ring_buffer ターゲット

ring_buffer ターゲットはメモリ内での迅速かつ簡単なイベント収集にのみ便利です。イベントセッションを停止すると、格納されている出力は破棄されます。

このセクションでは、XQuery を使用して、リングバッファの内容の XML 表現をより読みやすいリレーショナル行セットに変換する方法についても説明します。

ヒント

ring_buffer ターゲットを追加するときは、MAX_MEMORY パラメーターを1024 KB 以下に設定します。値を大きくすると、メモリ消費量が不必要に増加する可能性があります。

既定では、 MAX_MEMORY ring_bufferターゲットは SQL Server では制限されず、Azure SQL Database と Azure SQL Managed Instance では 32 MB (メガバイト)に制限されます。

次の例に示すように、ring_buffer ターゲットから XML に変換してデータを使用します。この変換中に、4 MB (メガバイト) XML ドキュメントに収まらないデータはすべて省略されます。したがって、より大きな MAX_MEMORY 値を使用して（またはこのパラメータをデフォルト値のままにして）リング・バッファに多くのイベントをキャプチャしても、XML マークアップと Unicode 文字列のオーバーヘッドを考慮すると、XML ドキュメントのサイズに4 MB の制限があるため、すべてのイベントを消費できない可能性があります。

XML ドキュメント内の truncated 属性が次に示すように 1 に設定されている場合、XML への変換中にリングバッファーの内容が省略されることがわかります。

<RingBufferTarget truncated="1" processingTime="0" totalEventsProcessed="284" eventCount="284" droppedCount="0" memoryUsed="64139">

CREATE EVENT SESSION と ring_buffer ターゲット

ring_buffer ターゲットとのイベントセッションを作成する例を次に示します。この例では、MAX_MEMORY パラメーターは 2 回表示されます。1 回は ring_buffer ターゲットメモリを 1024 KB (キロバイト)に設定し、1 回はイベントセッションバッファーメモリを 2 MB (メガバイト)に設定します。

CREATE EVENT SESSION [ring_buffer_lock_acquired_4]
    ON SERVER
    ADD EVENT sqlserver.lock_acquired
    (
        SET collect_resource_description=(1)
        ACTION(sqlserver.database_name)
        WHERE
        (
            [object_id]=(370100359)  -- ID of MyTable
            AND
            sqlserver.database_name='InMemTest2'
        )
    )
    ADD TARGET package0.ring_buffer
    (
        SET MAX_EVENTS_LIMIT = 98,
            MAX_MEMORY = 1024
    )
    WITH
    (
        MAX_MEMORY = 2 MB,
        MAX_DISPATCH_LATENCY = 3 SECONDS
    );

ring_buffer ターゲットが受け取る lock_acquired に関する XML 形式の出力

SELECT ステートメントによって取得されると、リングバッファーの内容が XML ドキュメントとして表示されます。次に例を示します。ただし、簡潔にするために、2 つ以外のすべての <event> 要素が削除されました。さらに、個々の <event> セクション内でも、いくつかの <data> 要素が削除されています。

<RingBufferTarget truncated="0" processingTime="0" totalEventsProcessed="6" eventCount="6" droppedCount="0" memoryUsed="1032">
  <event name="lock_acquired" package="sqlserver" timestamp="2016-08-05T23:59:53.987Z">
    <data name="mode">
      <type name="lock_mode" package="sqlserver"></type>
      <value>1</value>
      <text><![CDATA[SCH_S]]></text>
    </data>
    <data name="transaction_id">
      <type name="int64" package="package0"></type>
      <value>111030</value>
    </data>
    <data name="database_id">
      <type name="uint32" package="package0"></type>
      <value>5</value>
    </data>
    <data name="resource_0">
      <type name="uint32" package="package0"></type>
      <value>370100359</value>
    </data>
    <data name="resource_1">
      <type name="uint32" package="package0"></type>
      <value>0</value>
    </data>
    <data name="resource_2">
      <type name="uint32" package="package0"></type>
      <value>0</value>
    </data>
    <data name="database_name">
      <type name="unicode_string" package="package0"></type>
      <value><![CDATA[]]></value>
    </data>
    <action name="database_name" package="sqlserver">
      <type name="unicode_string" package="package0"></type>
      <value><![CDATA[InMemTest2]]></value>
    </action>
  </event>
  <event name="lock_acquired" package="sqlserver" timestamp="2016-08-05T23:59:56.012Z">
    <data name="mode">
      <type name="lock_mode" package="sqlserver"></type>
      <value>1</value>
      <text><![CDATA[SCH_S]]></text>
    </data>
    <data name="transaction_id">
      <type name="int64" package="package0"></type>
      <value>111039</value>
    </data>
    <data name="database_id">
      <type name="uint32" package="package0"></type>
      <value>5</value>
    </data>
    <data name="resource_0">
      <type name="uint32" package="package0"></type>
      <value>370100359</value>
    </data>
    <data name="resource_1">
      <type name="uint32" package="package0"></type>
      <value>0</value>
    </data>
    <data name="resource_2">
      <type name="uint32" package="package0"></type>
      <value>0</value>
    </data>
    <data name="database_name">
      <type name="unicode_string" package="package0"></type>
      <value><![CDATA[]]></value>
    </data>
    <action name="database_name" package="sqlserver">
      <type name="unicode_string" package="package0"></type>
      <value><![CDATA[InMemTest2]]></value>
    </action>
  </event>
</RingBufferTarget>

上の XML を取得するには、イベントセッションがアクティブになっている間に次の SELECT を発行します。 XML データが、システムビュー sys.dm_xe_session_targets から取得されます。

SELECT CAST(LocksAcquired.TargetXml AS XML) AS RBufXml
INTO #XmlAsTable
FROM (
    SELECT CAST(t.target_data AS XML) AS TargetXml
    FROM sys.dm_xe_session_targets AS t
    INNER JOIN sys.dm_xe_sessions AS s
        ON s.address = t.event_session_address
    WHERE t.target_name = 'ring_buffer'
        AND s.name = 'ring_buffer_lock_acquired_4'
) AS LocksAcquired;

SELECT *
FROM #XmlAsTable;

XML を行セットとして表示するための XQuery

上の XML をリレーショナル行セットとして表示するには、上の SELECT ステートメントに続けて次の T-SQL ステートメントを発行します。コメントの付いた行では、各 XQuery の使用方法が説明されています。

SELECT
    -- (A)
    ObjectLocks.value('(@timestamp)[1]', 'datetime') AS [OccurredDtTm],
    -- (B)
    ObjectLocks.value('(data[@name="mode"]/text)[1]', 'nvarchar(32)') AS [Mode],
    -- (C)
    ObjectLocks.value('(data[@name="transaction_id"]/value)[1]', 'bigint') AS [TxnId],
    -- (D)
    ObjectLocks.value('(action[@name="database_name" and @package="sqlserver"]/value)[1]', 'nvarchar(128)') AS [DatabaseName]
FROM #XmlAsTable
CROSS APPLY
    -- (E)
    TargetDateAsXml.nodes('/RingBufferTarget/event[@name="lock_acquired"]') AS T(ObjectLocks);

前の SELECT で使用されている XQuery に関するメモ

(A)

イベント <event> 要素での属性の値。
'(...)[1]' コンストラクトは、XMLデータ型変数と列の .value() XQueryメソッドの要件である反復ごとに１つの値のみが返されることを保証します。

(B)

name 属性が <text> と等しいセクション <data> 要素内のセクション mode 要素の内部値

(C)

name 属性が <value> と等しいセクション <data> 要素内のセクション transaction_id 要素の内部値

(D)

<event> には、<action> が含まれます。
<action> name= 属性が database_name と等しく、package= 属性が sqlserver と等しい（または package0 と等しくない）セクション <value> 要素の内部値

(E)

CROSS APPLY に等しい <event> 属性を持つ個々の name 要素ごとに lock_acquired は処理を繰り返します
これは、上の FROM 句から返された XML に対して行われます。

XQuery SELECT からの出力

次に示すのは、前の XQuery を含む T-SQL によって生成された行セットです。

OccurredDtTm              Mode    DatabaseName
------------              ----    ------------
2016-08-05 23:59:53.987   SCH_S   InMemTest2
2016-08-05 23:59:56.013   SCH_S   InMemTest2

event_stream ターゲット

event_stream ターゲットは、C# などの言語で記述された .NET プログラムでのみ使用できます。 C# やその他の .NET 開発者は、System.Diagnostics Microsoft.SqlServer.XEvents.Linq 名前空間の.NET Framework クラスを通じてイベントストリームにアクセスできます。このターゲットは T-SQL では使用できません。

The event data stream was disconnected because there were too many outstanding events. To avoid this error either remove events or actions from your session or add a more restrictive predicate filter to your session. ターゲットから読み取るときに event_stream エラー 25726 が発生した場合は、イベントストリームがクライアントがデータを消費するよりも速くデータでいっぱいになったことを意味します。これにより、データベースエンジンは、データベースエンジンのパフォーマンスに影響を与えないように、イベントストリームから切断します。

次の方法で共有

拡張イベントのターゲット

前提条件

パラメーター、アクション、フィールド

etw_classic_sync_target ターゲット

event_counter ターゲット

event_counter 目標によってキャプチャされる出力の例

event_file ターゲット

CREATE EVENT SESSION と event_file ターゲット

sys.fn_xe_file_target_read_file() 関数

event_file ターゲットに格納されているデータ

histogram ターゲット

アクションを含むヒストグラムターゲット

使用可能なアクションを検出するための SELECT

イベントフィールドを含むヒストグラムターゲット

選択したイベントで使用可能なフィールドを検出する SELECT

pair_matching ターゲット

開始イベントと終了イベントのペアのマッチングが可能なフィールドの検索

pair_matching ターゲットの例

ring_buffer ターゲット

CREATE EVENT SESSION と ring_buffer ターゲット

ring_buffer ターゲットが受け取る lock_acquired に関する XML 形式の出力

XML を行セットとして表示するための XQuery

前の SELECT で使用されている XQuery に関するメモ

XQuery SELECT からの出力

event_stream ターゲット

XEvent の名前空間

フィードバック

その他のリソース

次の方法で共有

拡張イベントのターゲット

前提条件

パラメーター、アクション、フィールド

etw_classic_sync_target ターゲット

event_counter ターゲット

event_counter 目標によってキャプチャされる出力の例

event_file ターゲット

CREATE EVENT SESSION と event_file ターゲット

sys.fn_xe_file_target_read_file() 関数

event_file ターゲットに格納されているデータ

histogram ターゲット

アクションを含むヒストグラム ターゲット

使用可能なアクションを検出するための SELECT

イベント フィールドを含むヒストグラム ターゲット

選択したイベントで使用可能なフィールドを検出する SELECT

pair_matching ターゲット

開始イベントと終了イベントのペアのマッチングが可能なフィールドの検索

pair_matching ターゲットの例

ring_buffer ターゲット

CREATE EVENT SESSION と ring_buffer ターゲット

ring_buffer ターゲットが受け取る lock_acquired に関する XML 形式の出力

XML を行セットとして表示するための XQuery

前の SELECT で使用されている XQuery に関するメモ

XQuery SELECT からの出力

event_stream ターゲット

XEvent の名前空間

フィードバック

その他のリソース

アクションを含むヒストグラムターゲット

イベントフィールドを含むヒストグラムターゲット