sys.fn_xe_file_target_read_file（Transact-SQL）

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

读取扩展事件 event_file 目标创建的事件日志 XEL 文件。 结果集中的每一行都表示一个事件。 事件数据以 XML 格式返回。

也可以由 SQL Server Management Studio 读取 XEL 文件。 有关演练，请参阅 快速入门：扩展事件。

Transact-SQL 语法约定

语法

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

参数

path

要读取的文件的路径。 路径 为 nvarchar（260）， 没有默认值。

• 在本地文件系统中与文件一起使用时， 路径 必须包含事件会话日志文件的名称。 文件名可以包含 * 为通配符，用于从多个文件中读取数据。

• 在 Azure 存储容器中与 Blob 一起使用时， 路径 是由两个部分的串联构造的 HTTP URL：

  1. Azure 存储存储容器的路径，后跟斜杠（/）。

  2. 应读取的容器中 Blob 名称的常见前缀。 若要读取单个 Blob，请使用 Blob 的全名。

  例如，使用https://<storage-account-name>.blob.core.windows.net/container-name>/xe_session路径从名称开头xe_session的所有 Blob 检索数据，而不考虑 blob 名称的其余部分（包括扩展）。 无法指定通配符。

mdpath

与路径参数指定的 文件或文件相对应的元数据文件的路径 。 mdpath 为 nvarchar（260）， 没有默认值。

在 SQL Server 2012（11.x）及更高版本中，不需要此参数。 保留它以实现向后兼容性，适用于在早期版本的 SQL Server 中生成的日志文件。 在 SQL Server 2016（13.x）及更高版本中，可以指定此参数， NULL因为 .xem 不再使用文件。

initial_file_name

要从 路径读取的第一个文件。 initial_file_name为 nvarchar（260），没有默认值。 如果NULL指定为参数，则读取路径中找到的所有文件。

文件名必须是在具有相同路径的sys.fn_xe_file_target_read_file函数调用的结果集中返回的值。

initial_offset

用于指定以前读取的最后一个偏移量。 将所有事件跳过到偏移量（含）。 事件枚举在指定偏移量后开始。 initial_offset是偏重的。 如果 NULL 指定为参数，则读取整个文件。

返回的表

注解

通过在 Management Studio 中执行 sys.fn_xe_file_target_read_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 托管实例或 Azure SQL 数据库中，目标创建 event_file 的文件始终以 Blob 的形式存储在 Azure 存储容器中。

如果凭据允许访问 Azure 存储容器，则可以用于 sys.fn_xe_file_target_read_file 从这些 Blob 读取数据。 有关演练，请查看在 Azure 存储中创建具有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 存储容器中的 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
);

从 blob 读取 xe_session_0_133614763336380000.xel 数据，从偏移量 33280 开始。

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会话