sys.fn_xe_file_target_read_file(Transact-SQL)

適用対象:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceMicrosoft Fabric の SQL データベース

拡張イベント event_file ターゲットによって作成されたイベント ログ XEL ファイルを読み取ります。 結果セットの各行はイベントを表します。 イベント データは XML 形式で返されます。

XEL ファイルは、SQL Server Management Studio でも読み取ることができます。 チュートリアルについては、「 Quickstart: 拡張イベント」を参照してください。

Transact-SQL 構文表記規則

構文

sys.fn_xe_file_target_read_file ( path , mdpath , initial_file_name , initial_offset )

引数

path

読み取るファイルのパスです。 path は既定値なしで nvarchar(260) です。

• ローカル ファイル システムのファイルと共に使用する場合、 パス にはイベント セッション ログ ファイルの名前を含める必要があります。 ファイル名には、複数のファイルからデータを読み取るワイルドカードとして * を含めることができます。

• Azure Storage コンテナー内の BLOB と共に使用する場合、 パス は 2 つの部分を連結して構築された HTTP URL です。

  1. Azure Storage ストレージ コンテナーへのパス。その後にスラッシュ (/)。

  2. 読み取る必要があるコンテナー内の BLOB の名前の共通プレフィックス。 1 つの BLOB を読み取る場合は、BLOB の完全な名前を使用します。

  たとえば、パスとして https://<storage-account-name>.blob.core.windows.net/container-name>/xe_session を使用すると、拡張子を含む BLOB 名の残りの部分に関係なく、名前が xe_session で始まるすべての BLOB からデータが取得されます。 ワイルドカードを指定できません。

mdpath

path 引数で指定されたファイルに対応するメタデータ ファイルへのパス。 mdpath は既定値なしで nvarchar(260) です。

SQL Server 2012 (11.x) 以降のバージョンでは、このパラメーターは必要ありません。 以前のバージョンの SQL Server で生成されたログ ファイルの下位互換性のために保持されます。 SQL Server 2016 (13.x) 以降のバージョンでは、NULL ファイルが使用されなくなったので、このパラメーターは.xemとして指定できます。

initial_file_name

path から読み取る最初のファイル。 initial_file_name は既定値なしで nvarchar(260) です。 引数として NULL を指定すると、 path 内のすべてのファイルが読み取られます。

ファイル名は、同じsys.fn_xe_file_target_read_fileを持つ関数呼び出しの結果セットで返される値である必要があります。

initial_offset

前に最後に読み取ったオフセットを指定するために使用されます。 オフセット (含む) まですべてのイベントをスキップします。 イベント列挙は、指定されたオフセットの後に開始されます。 initial_offset は bigint です。 引数として NULL を指定すると、ファイル全体が読み取られます。

Note

initial_file_name と initial_offset はペアの引数です。 いずれかの引数に値を指定する場合は、他の引数の値を指定する必要があります。

返されるテーブル

列名	データ型	説明
module_guid	uniqueidentifier	イベント モジュール GUID。 NULL 値は許可されません。
package_guid	uniqueidentifier	イベント パッケージの GUID です。 NULL 値は許可されません。
object_name	nvarchar (256)	イベントの名前です。 NULL 値は許可されません。
event_data	nvarchar(max)	イベントの内容 (XML 形式)。 NULL 値は許可されません。
file_name	nvarchar(260)	イベントを含むファイルの名前。 NULL 値は許可されません。
file_offset	bigint	イベントを含むファイル内のブロックのオフセット。 NULL 値は許可されません。
timestamp_utc	datetime2(7)	イベントの日付と時刻 (UTC タイムゾーン)。 NULL 値は許可されません。 適用対象: SQL Server 2017 (14.x) 以降のバージョン、Azure SQL Database、および Azure SQL Managed Instance。

解説

Management Studio で sys.fn_xe_file_target_read_file を実行して大きな結果セットを読み取る場合、エラーが発生する可能性があります。 Results to File モード (SQL Server Management Studio では、Ctrl + Shift + F) を使用して、大きな結果セットを人間が判読できるファイルにエクスポートし、代わりに別のツールでファイルを読み取ります。

SQL Server 2008 (10.0.x) と SQL Server 2008 R2 (10.50.x) は、XEL および XEM 形式で生成されたトレース結果を受け入れます。 SQL Server 2012 (11.x) 拡張イベントでは、XEL 形式のトレース結果のみがサポートされます。 Management Studio を使用して、トレース結果を XEL 形式で読み取うことをお勧めします。

Azure SQL

Azure SQL Managed Instance または Azure SQL Database では、 event_file ターゲットによって作成されたファイルは、常に BLOB として Azure Storage コンテナーに格納されます。

Azure Storage コンテナーへのアクセスを許可する資格情報が存在する場合は、 sys.fn_xe_file_target_read_file を使用してこれらの BLOB からデータを読み取ることができます。 チュートリアルについては、「 Azure Storage でevent_file ターゲットを持つイベント セッションを作成する」を参照してください。

ローカル ファイル システム パスを指定すると、次のようなエラー メッセージが表示されます。

Msg 40538, Level 16, State 3, Line 15
A valid URL beginning with 'https://' is required as value for any filepath specified.

アクセス許可

SQL Server 2019 (15.x) 以前のバージョンでは、サーバーに対する VIEW SERVER STATE アクセス許可が必要です。

SQL Server 2022 (16.x) 以降のバージョンでは、サーバー VIEW SERVER PERFORMANCE STATE アクセス許可が必要です。

例

A. ローカル ファイル システム内のファイルからデータを取得する

SQL Server 2014 (12.x) 以前のバージョンの場合、次の例では、 .xel ファイルと .xem ファイルの両方を含むすべてのファイルからすべての行を取得します。 この例では、ファイル ターゲットとメタファイルは、 C:\traces\ フォルダー内のトレース フォルダーにあります。

SELECT *
FROM sys.fn_xe_file_target_read_file('C:\traces\*.xel', 'C:\traces\metafile.xem', NULL, NULL);

SQL Server 2016 (13.x) 以降のバージョンでは、次の例では、既定のフォルダー内のすべての .xel ファイル内のイベントを取得します。 既定の場所は、インスタンスのインストール フォルダー内で \MSSQL\Log されます。

SELECT *
FROM sys.fn_xe_file_target_read_file('*.xel', NULL, NULL, NULL);

SQL Server 2017 (14.x) 以降のバージョンでは、次の例では、組み込みのsystem_health セッションから、最終日のデータのみを取得します。 system_health セッションは、既定では SQL Server に含まれている拡張イベント セッションです。 詳細については、「system_health セッションの使用」を参照してください。

SELECT *
FROM sys.fn_xe_file_target_read_file('system_health*.xel', NULL, NULL, NULL)
WHERE CAST (timestamp_utc AS DATETIME2 (7)) > DATEADD(DAY, -1, GETUTCDATE());

B: Azure Storage コンテナー内の BLOB からデータを取得する

名前が xe_session_ で始まるコンテナー内のすべての BLOB からデータを読み取ります。

SELECT *
FROM sys.fn_xe_file_target_read_file(
    'https://<storage-account-name>.blob.core.windows.net/<container-name>/xe_session_',
    NULL,
    NULL,
    NULL
);

xe_session_0_133614763336380000.xel BLOB からデータを読み取る。

SELECT *
FROM sys.fn_xe_file_target_read_file(
    'https://<storage-account-name>.blob.core.windows.net/<container-name>/xe_session_0_133614763336380000.xel',
    NULL,
    NULL,
    NULL
);

オフセット 33280 以降の xe_session_0_133614763336380000.xel BLOB からデータを読み取る。

SELECT *
FROM sys.fn_xe_file_target_read_file(
    'https://<storage-account-name>.blob.core.windows.net/<container-name>/xe_session_',
    NULL,
    'https://<storage-account-name>.blob.core.windows.net/<container-name>/xe_session_0_133614763336380000.xel',
    33280
);

関連するコンテンツ

• 拡張イベントの動的管理ビュー
• 拡張イベント カタログ ビュー (Transact-SQL)
• 拡張イベントの概要
• 拡張イベントのターゲット
• SQL Server Management Studio でイベント データを表示する
• 既存の SQL トレース スクリプトから拡張イベント セッションへの変換
• system_health セッションを使用する