sys.fn_xe_file_target_read_file (Transact-SQL)

项目
06/02/2023

适用于：SQL Server Azure SQL 数据库 Azure SQL 托管实例

读取扩展事件异步文件目标创建的文件。每行返回一个 XML 格式的事件。

扩展事件 event_file 目标以人类不可读的二进制格式存储它接收的数据。使用 sys.fn_xe_file_target_read_file 函数读取文件的内容.xel。也可以从 Management Studio 读取这些文件。有关演练，请参阅快速入门：SQL Server中的扩展事件。

Transact-SQL 语法约定

语法

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

参数

path

要读取的文件的路径。路径可以包含通配符，并包含文件的名称。路径为 nvarchar (260) 。没有默认值。在 Azure SQL Database 的上下文中，此值是 Azure 存储中文件的 HTTP URL。

mdpath

与 path 参数指定的一个或多个文件相对应的元数据文件 的路径 。 mdpath 为 nvarchar (260) 。没有默认值。 SQL Server 2012 (11.x) 不需要 mdpath 参数。但是，为了在以前的 SQL Server 版本中生成的日志文件的向后兼容性，需要维护该参数。从 SQL Server 2016 (13.x) 开始，此参数可以指定为 null，因为.xem不再使用文件。

initial_file_name

要从路径中读取的第一个文件。 initial_file_name 为 nvarchar (260) 。没有默认值。如果指定 null 作为参数，则会读取 在 path 中找到的所有文件。

注意

initial_file_name 和 initial_offset 是配对参数。如果为其中一个参数指定值，则必须为另一个参数也指定值。

initial_offset

用于指定之前读取的上一个偏移量并跳过该偏移量之前的所有事件（包括该偏移量处的事件）。事件枚举在指定偏移量后开始。 initial_offset是大。如果将 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)	适用于：SQL Server 2017 (14.x) 及更高版本以及 Azure SQL Database。事件) UTC 时区 (日期和时间。不可为 null。

备注

通过在 Management Studio 中执行 sys.fn_xe_file_target_read_file 来读取大型结果集可能会导致错误。使用 SSMS 中的“ 结果到文件” 模式 (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 托管实例或 Azure SQL 数据库中，将 .xel 文件存储在 Azure Blob 存储中。可以使用 sys.fn_xe_file_target_read_file 从你自己创建的扩展事件会话进行读取，并存储在 Azure Blob 存储中。有关示例演练，请参阅 Azure SQL 数据库和 Azure SQL 托管实例中扩展事件的事件文件目标代码。

如果为本地文件系统指定通配符和/或路径，将收到类似于以下内容的错误消息：

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

权限

要求具有服务器的 VIEW SERVER 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())