sys.fn_xe_file_target_read_file (Transact-SQL)
適用対象: 
SQL Server Azure SQL Database Azure SQL Managed Instance
拡張イベント非同期ファイル ターゲットによって作成されたファイルを読み取ります。 行ごとに、XML 形式の 1 つのイベントが返されます。
拡張イベント event_file ターゲットは、受信したデータを人間が判読できないバイナリ形式で格納します。 sys.fn_xe_file_target_read_file関数を使用して、.xel ファイルの内容を読み取ります。 これらのファイルは、Management Studio から読み取ることもできます。 チュートリアルについては、「 Quickstart: 拡張イベント」を参照してください。
構文
sys.fn_xe_file_target_read_file ( path , mdpath , initial_file_name , initial_offset )
引数
path
読み取るファイルのパスです。 path にはワイルドカードを含め、ファイルの名前を含めることができます。 path は既定値なしで nvarchar(260) です。 Azure SQL Database のコンテキストでは、この値は Azure Storage 内のファイルへの HTTP URL です。
mdpath
path 引数で指定されたファイルに対応するメタデータ ファイルへのパス。 mdpath は既定値なしで nvarchar(260) です。
SQL Server 2012 (11.x) 以降のバージョンでは、このパラメーターは必要ありません。 以前のバージョンの SQL Server で生成されたログ ファイルについては、下位互換性のために保持されていました。 SQL Server 2016 (13.x) 以降のバージョンでは、.xem ファイルが使用されなくなったので、このパラメーターはNULLとして指定できます。
initial_file_name
path から読み取る最初のファイル。 initial_file_name は既定値なしで nvarchar(260) です。 引数として NULL を指定すると、 path 内のすべてのファイルが読み取られます。
Note
initial_file_name と initial_offset はペアの引数です。 いずれかの引数に値を指定する場合は、他の引数の値を指定する必要があります。
initial_offset
以前に読み取られた最後のオフセットを指定します。そのオフセットまでのすべてのイベントがスキップされます。 イベント列挙は、指定されたオフセットの後に開始されます。 initial_offset は bigint です。 引数として NULL を指定すると、ファイル全体が読み取られます。
返されるテーブル
| 列名 | データ型 | 説明 |
|---|---|---|
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 |
解説
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 で、 .xel ファイルを Azure Blob Storage に格納します。 sys.fn_xe_file_target_read_file を使用して、自分で作成した拡張イベント セッションから読み取り、Azure Blob Storage に格納できます。 たとえば、チュートリアル 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());