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

项目
11/15/2024

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

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

创建 Azure 存储帐户或查找现有的合适帐户来使用。
在此存储帐户中创建容器。
使用 RBAC 角色分配或 SAS 令牌授予数据库引擎对容器的必要访问权限。
在创建事件会话的数据库或托管实例中创建凭据。
创建、启动和使用事件会话。

创建存储帐户和容器

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

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

是一个 Standard general-purpose v2 帐户。
其冗余类型与创建事件会话的 Azure SQL 数据库、弹性池或托管实例的冗余类型相匹配。
- 对于本地冗余的 Azure SQL 资源，请使用 LRS、GRS 或 RA-GRS。对于区域冗余的 Azure SQL 资源，请使用 ZRS、GZRS 或 RA-GZRS。有关详细信息，请参阅 Azure 存储冗余。
使用 Hot Blob 访问层。
与 Azure SQL 数据库、弹性池或托管实例位于同一 Azure 区域中。

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

记下已创建的存储帐户和容器的名称。在后续步骤中，将会用到这些名称。

授予对容器的访问权限

要读取和写入事件数据，数据库引擎需要拥有对容器的特定访问权限。可以通过以下两种方式之一授予此访问权限，具体取决于所选的身份验证类型：

如果将托管标识用于 Microsoft Entra 身份验证，请将容器的存储 Blob 数据参与者 RBAC 角色分配给 Azure SQL 逻辑服务器或 Azure SQL 托管实例的托管标识。

注意

使用托管标识与扩展事件会话的功能目前处于预览阶段。
如果使用基于机密的身份验证，请为容器创建 SAS 令牌。

要使用此身份验证类型，必须启用“允许存储帐户密钥访问”选项。有关详细信息，请参阅阻止对 Azure 存储帐户进行共享密钥授权。

使用托管标识授予访问权限

在 Azure 门户中，导航到 Azure SQL 逻辑服务器或 Azure SQL 托管实例的“标识”页面，并确保托管标识已分配。有关详细信息，请参阅 Microsoft Entra 中用于 Azure SQL 的托管标识。
在 Azure 门户中，导航到要在其中存储事件数据的存储容器。在“访问控制 (IAM)”页上，选择“添加”，将存储 Blob 数据参与者 RBAC 角色分配给逻辑服务器或 SQL 托管实例的托管标识。

如果逻辑服务器或 SQL 托管实例已启用系统分配的托管标识，请将角色分配给该标识。如果系统分配的标识已禁用，但存在一个或多个用户分配的标识，请将角色分配给指定为主要标识的用户分配的标识。

有关详细信息，请参阅分配用于访问 Blob 数据的 Azure 角色。
创建凭据以指示数据库引擎使用特定容器 URL 的托管标识向 Azure 存储进行身份验证。
- SQL 数据库
- SQL 托管实例
创建数据库范围的凭据。使用 SSMS 或 ADS 等客户端工具，打开一个新的查询窗口，连接到创建事件会话的数据库，然后粘贴以下 T-SQL 批处理。请确保已连接到用户数据库，而不是连接到 master 数据库。

注意

执行以下 T-SQL 批处理需要 CONTROL 数据库权限，该权限由数据库所有者 (dbo)、db_owner 数据库角色的成员和逻辑服务器管理员持有。
```
/*
(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://<storage-account-name>.blob.core.chinacloudapi.cn/<container-name>'
          )
    DROP DATABASE SCOPED CREDENTIAL [https://<storage-account-name>.blob.core.chinacloudapi.cn/<container-name>];

/*
When using managed identity, the credential does not contain a secret
*/
CREATE DATABASE SCOPED CREDENTIAL [https://<storage-account-name>.blob.core.chinacloudapi.cn/<container-name>]
WITH IDENTITY = 'MANAGED IDENTITY';
```
创建服务器范围的凭据。使用 SSMS 或 ADS 等客户端工具，打开一个新的查询窗口，连接到创建事件会话的托管实例上的 master 数据库，然后粘贴以下 T-SQL 批处理。

注意

执行以下 T-SQL 批处理需要 master 数据库中的 CONTROL 数据库权限，该权限由 master 中的 db_owner 数据库角色成员以及托管实例上的 sysadmin 服务器角色成员持有。
```
/*
(Re-)create a credential.
The name of the credential must match the URL of the blob container.
*/
IF EXISTS (
          SELECT 1
          FROM sys.credentials
          WHERE name = 'https://<storage-account-name>.blob.core.chinacloudapi.cn/<container-name>'
          )
    DROP CREDENTIAL [https://<storage-account-name>.blob.core.chinacloudapi.cn/<container-name>];

/*
When using managed identity, the credential does not contain a secret
*/
CREATE CREDENTIAL [https://<storage-account-name>.blob.core.chinacloudapi.cn/<container-name>]
WITH IDENTITY = 'MANAGED IDENTITY';
```
在执行此批处理之前，请进行以下更改：
- 在出现的三种 https://<storage-account-name>.blob.core.chinacloudapi.cn/<container-name> 中，请将 <storage-account-name> 替换为存储帐户的名称，并将 <container-name> 替换为容器的名称。

使用 SAS 令牌授予访问权限

在 Azure 门户中，导航到所创建的存储帐户和容器。选择容器，然后导航到“设置共享访问令牌 >”。

SAS 令牌必须满足以下要求：
- 权限设置为 Read、Write、Delete、List。
- 开始时间和过期时间必须能够覆盖事件会话的生存期。创建的 SAS 令牌仅在此时间间隔内有效。
- 无 IP 地址限制。
选择“生成 SAS 令牌和 URL”按钮。 SAS 令牌位于“Blob SAS 令牌”框中。可以复制它以在下一步中使用。

重要

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

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

SQL 数据库
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://<storage-account-name>.blob.core.chinacloudapi.cn/<container-name>'
          )
    DROP DATABASE SCOPED CREDENTIAL [https://<storage-account-name>.blob.core.chinacloudapi.cn/<container-name>];

/*
The secret is the SAS token for the container. The Read, Write, and List permissions are set.
*/
CREATE DATABASE SCOPED CREDENTIAL [https://<storage-account-name>.blob.core.chinacloudapi.cn/<container-name>]
WITH IDENTITY = 'SHARED ACCESS SIGNATURE',
    SECRET = '<sas-token>';

在执行该批处理之前，请进行以下更改：

在出现的三种 https://<storage-account-name>.blob.core.chinacloudapi.cn/<container-name> 中，请将 <storage-account-name> 替换为存储帐户的名称，并将 <container-name> 替换为容器的名称。
在 SECRET 子句中，请将 <sas-token> 替换为在上一步骤中复制的 SAS 令牌。

将 SAS 令牌存储在服务器范围的凭据中。使用 SSMS 或 ADS 等客户端工具，打开一个新的查询窗口，连接到创建事件会话的托管实例上的 master 数据库，然后粘贴以下 T-SQL 批处理。

注意

执行以下 T-SQL 批处理需要 master 数据库中的 CONTROL 数据库权限，该权限由 master 中的 db_owner 数据库角色成员以及托管实例上的 sysadmin 服务器角色成员持有。

/*
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 ENCRYPTION BY PASSWORD = '<password>';

/*
(Re-)create a credential.
The name of the credential must match the URL of the blob container.
*/
IF EXISTS (
          SELECT 1
          FROM sys.credentials
          WHERE name = 'https://<storage-account-name>.blob.core.chinacloudapi.cn/<container-name>'
          )
    DROP CREDENTIAL [https://<storage-account-name>.blob.core.chinacloudapi.cn/<container-name>];

/*
The secret is the SAS token for the container. The Read, Write, and List permissions are set.
*/
CREATE CREDENTIAL [https://<storage-account-name>.blob.core.chinacloudapi.cn/<container-name>]
WITH IDENTITY = 'SHARED ACCESS SIGNATURE',
    SECRET = '<sas-token>';

在执行该批处理之前，请进行以下更改：

在 CREATE MASTER KEY 语句中，将 <password> 替换为将保护主密钥的实际密码。有关详细信息，请参阅 CREATE MASTER KEY。
在出现的三种 https://<storage-account-name>.blob.core.chinacloudapi.cn/<container-name> 中，请将 <storage-account-name> 替换为存储帐户的名称，并将 <container-name> 替换为容器的名称。
在 SECRET 子句中，请将 <sas-token> 替换为在上一步骤中复制的 SAS 令牌。

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

创建凭据后，可以创建事件会话。与创建凭据不同，创建事件会话无需 CONTROL 权限。创建凭据后，即使你的权限受到更多限制，也可以创建事件会话。请参阅权限了解所需的特定权限。

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

“新建会话 SSMS”对话框的屏幕截图，其中显示了选中 sql_batch_starting 事件的事件选择页。

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

注意

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

“新建会话 SSMS”对话框的屏幕截图，其中显示了“数据存储选择”页，并在其中选择了 event_file 目标并输入了存储 URL。

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

SQL 数据库
SQL 托管实例

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

CREATE EVENT SESSION [example-session] ON SERVER
ADD EVENT sqlserver.sql_batch_starting
ADD TARGET package0.event_file(SET filename=N'https://<storage-account-name>.blob.core.chinacloudapi.cn/<container-name>/example-session.xel')
GO

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

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

在此数据库或托管实例中执行 T-SQL 批处理时，会话会将事件写入存储容器中的 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中创建事件会话。

通过