在 Azure 存储中创建具有 event_file 目标的事件会话

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

本演练中的大致步骤包括:

  1. 创建 Azure 存储帐户或查找现有适合帐户。
  2. 在该存储帐户中创建容器
  3. 创建具有此容器所需访问权限的 SAS 令牌
  4. 创建凭据以将 SAS 令牌存储在创建事件会话的数据库或托管实例中
  5. 创建、启动和使用事件会话

创建存储帐户和容器

有关如何在 Azure 存储中创建存储帐户的详细说明,请参阅创建存储帐户。 了解如何使用 Azure 门户、PowerShell、Azure SQL、ARM 模板或 Bicep 模板创建存储帐户。

我们建议您使用满足以下要求的帐户:

  • 是一个 Standard general-purpose v2 帐户。
  • 其冗余类型与创建事件会话的 Azure SQL 数据库、弹性池或托管实例的冗余类型相匹配。
  • 使用 Hot Blob 访问层
  • 与 Azure SQL 数据库、弹性池或托管实例位于同一 Azure 区域中。

接下来,使用 Azure 门户在该存储帐户中创建容器。 还可以使用 PowerShell使用 Azure CLI 来创建容器。

记下使用的存储帐户和容器的名称。

创建 SAS 令牌

运行事件会话的数据库引擎应该具有对此存储容器的特定访问权限。 通过为容器创建 SAS 令牌来授予此访问权限。 该令牌必须满足以下要求:

  • 具有 rwl (ReadWriteList) 权限
  • 具备包含事件会话生存期的开始时间和到期时间
  • 无 IP 地址限制

在 Azure 门户中,查找创建的存储帐户和容器。 选择容器,然后导航到“设置共享访问令牌 >”。 将“权限”设置为 ReadWriteList,并设置“开始”和“到期”日期和时间。 创建的 SAS 令牌仅在此时间间隔内有效。

选择“生成 SAS 令牌和 URL”按钮。 SAS 令牌位于“Blob SAS 令牌”框中。 可以复制它以在下一步中使用。

重要

SAS 令牌提供对此容器的读取和写权限。 将其视为处理密码或任何其他机密。

Screenshot of the Shared Access Tokens screen for an Azure Storage container, with a generated SAS token for an example container.

创建用于存储 SAS 令牌的凭据

在Azure SQL 数据库中,使用数据库范围的凭据来存储 SAS 令牌。 在Azure SQL 托管实例中,使用服务器范围的凭据。

将 SAS 令牌存储在数据库范围的凭据中。 使用 SSMS 或 ADS 等客户端工具,打开一个新的查询窗口,连接到创建事件会话的数据库,然后粘贴以下 T-SQL 批处理。 请确保已连接到用户数据库,而不是连接到 master 数据库。

注意

执行以下 T-SQL 批处理需要 CONTROL 数据库权限,该权限由数据库所有者 (dbo)、db_owner 数据库角色的成员和逻辑服务器管理员持有。

/*
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 URL of the blob container.
*/
IF EXISTS (
          SELECT 1
          FROM sys.database_credentials
          WHERE name = 'https://exampleaccount4xe.blob.core.chinacloudapi.cn/xe-example-container'
          )
    DROP DATABASE SCOPED CREDENTIAL [https://exampleaccount4xe.blob.core.chinacloudapi.cn/xe-example-container];

/*
The secret is the SAS token for the container. The Read, Write, and List permissions are set.
*/
CREATE DATABASE SCOPED CREDENTIAL [https://exampleaccount4xe.blob.core.chinacloudapi.cn/xe-example-container]
WITH IDENTITY = 'SHARED ACCESS SIGNATURE',
     SECRET = 'sp=rwl&st=2023-10-17T23:28:32Z&se=2023-10-18T07:28:32Z&spr=https&sv=2022-11-02&sr=c&sig=REDACTED';

在执行该批处理之前,请进行以下更改:

  • 在出现的三种 https://exampleaccount4xe.blob.core.chinacloudapi.cn/xe-example-container 中,请将 exampleaccount4xe 替换为存储帐户的名称,并将 xe-example-container 替换为容器的名称。
  • SECRET 子句中单引号之间的整个字符串替换为在上一步骤中复制的 SAS 令牌。

创建、启动和停止事件会话

创建包含 SAS 令牌的凭据后,即可创建事件会话。 创建事件会话不需要 CONTROL 权限。 如果已存在具有正确 SAS 令牌的凭据,那么即使拥有限制性更高的权限集,也可以创建事件会话。 请参阅权限了解所需的特定权限。

若要在 SSMS 中创建新的事件会话,请展开 扩展事件 节点。 此节点位于 Azure SQL 数据库的数据库文件夹下,位于 Azure SQL 托管实例的管理文件夹下。 右键单击“会话”文件夹,然后选择“新建会话...”。在“常规”页上,输入在此示例中为 example-session 的会话的名称。 在“事件”页上,选择要添加到会话的一个或多个事件。 在此例中,选择了 sql_batch_starting 事件。

Screenshot of the New Session SSMS dialog showing the event selection page with the sql_batch_starting event selected.

在“数据存储”页上,选择 event_file 作为目标类型,并将存储容器的 URL 粘贴到“存储 URL”框中。 在此 URL 的末尾键入一个正斜杠 (/),后跟文件 (blob) 名称。 在该示例中,blob 名称为 example-session.xel,整个 URL 为 https://exampleaccount4xe.blob.core.chinacloudapi.cn/xe-example-container/example-session.xel

注意

对于 SQL 托管实例,请使用“脚本”按钮创建会话的 T-SQL 脚本,而不是粘贴“数据存储”页面上的存储容器 URL。 将容器 URL 指定为 filename 参数的值,类似于下面的示例 SQL 托管实例,并执行脚本来创建会话。

Screenshot of the New Session SSMS dialog showing the data storage selection page with an event_file target selected and an entered storage URL.

配置会话后,可以选择“脚本”按钮来创建会话的 T-SQL 脚本,以便稍后保存。 下面是示例会话的脚本:

CREATE EVENT SESSION [example-session] ON DATABASE
ADD EVENT sqlserver.sql_batch_starting
ADD TARGET package0.event_file(SET filename=N'https://exampleaccount4xe.blob.core.chinacloudapi.cn/xe-example-container/example-session.xel')
GO

选择“确定”以创建会话。

在对象资源管理器中,展开“会话”文件夹以查看创建的事件会话。 默认情况下,会话在创建时不会启动。 要启动会话,请右键单击会话名称,然后选择“启动会话”。 如果会话正在运行,稍后可以同样通过选择“停止会话”来停止会话。

在此数据库或托管实例中执行 T-SQL 批处理时,会话会将事件写入 xe-example-container 存储容器的 example-session.xel blob 中。

若要停止会话,请在对象资源管理器中右键单击该会话,然后选择“停止会话”。

查看事件数据

可以在 SQL Server Management Studio (SSMS) 事件查看器 UI 中查看事件数据,并在其中使用筛选器和聚合来分析捕获的数据。 有关在 SSMS 中使用事件查看器的详细信息,请参阅 在 SSMS 中查看事件数据

从 Azure 存储下载 xel 文件

提示

如果使用 SSMS v19.2 或更高版本,则无需下载本节中所述的 xel 文件。 在这些版本中,SSMS 直接从 Azure 存储读取每个会话的 xel 文件。 有关详细信息,请参阅 改进 Azure SQL 中的扩展事件 博客。

从存储容器下载会话的 xel Blob,并将其另存为本地文件。 在Azure 门户中,找到使用的存储帐户,选择“数据存储”下的“容器”,然后选择为事件会话创建的容器。 会话的 Blob 将会话名称作为其名称的第一部分,并带有数字后缀。 选择省略号 (...) 以显示 Blob 的上下文菜单,然后选择“下载”。

可以在一个操作中通过安装 Azure 存储资源管理器来下载多个 xel blob。

下载 xel 文件后,在 SSMS 中将其打开。 在 SSMS 主菜单上,转到“文件”并选择“打开”。 如果有单个 xel 文件,请选择“文件...”,然后浏览到下载的文件。 如果同一事件会话(称为滚动更新文件)生成了多个 xel 文件,则可以通过 “合并扩展事件文件...”对话框在事件查看器中打开所有这些文件。

使用 T-SQL 查看事件数据

要使用 T-SQL 读取事件会话数据,请使用 sys.fn_xe_file_target_read_file() 函数。 要在与创建事件会话的数据库或托管实例不同的数据库或托管实例中使用此函数,请创建凭据,以便数据库引擎通过事件 blob 访问存储容器。

有关更详细的演练,请参阅在 SSMS中创建事件会话