Azure Storage で event_file ターゲットとのイベントセッションを作成する

[アーティクル]
11/12/2024

適用対象: Azure SQL データベース Azure SQL Managed Instance

このチュートリアルの手順の概要は次のとおりです:

Azure Storage アカウントを作成するか、使用する既存の適切なアカウントを見つけます。
このストレージアカウント内にコンテナーを作成します。
RBAC ロールの割り当てまたは SAS トークンを使用して、データベースエンジンにコンテナーへの必要なアクセスを許可します。
イベントセッションを作成するデータベースまたはマネージドインスタンス内に資格情報を作成します。
イベントセッションを作成、開始、使用します。

ストレージアカウントとコンテナーの作成

Azure Storage でストレージアカウントを作成する方法の詳細は、「ストレージアカウントを作成する」を参照してください。 Azure portal、PowerShell、Azure SQL、ARM テンプレート、または Bicep テンプレートを使用してストレージアカウントを作成する方法について説明します。

次のようなアカウントを使用することをお勧めします:

Standard general-purpose v2 アカウントである。
冗長性の種類が、イベントセッションが作成される Azure SQL データベース、エラスティックプール、またはマネージドインスタンスの冗長性に一致する。
- ローカル冗長 Azure SQL リソースの場合は、LRS、GRS、または RA-GRS を使用します。ゾーン冗長 Azure SQL リソースの場合は、ZRS、GZRS、または RA-GZRS を使用します。詳細については、「Azure Storage の冗長性」を参照してください。
Hot BLOB アクセス層を使用します。
Azure SQL データベース、エラスティックプール、またはマネージドインスタンスと同じ Azure リージョンにある。

次に、Azure portal を使用してこのストレージアカウントにコンテナーを作成します。 PowerShell または Azure CLI を使用してコンテナーを作成することもできます。

作成した "ストレージアカウント" と "コンテナー" の名前をメモします。それらは次の手順の中で使用します。

コンテナーへのアクセスを許可する

イベントデータの読み取りと書き込みを行うには、データベースエンジンにコンテナーへの特定のアクセスが必要です。認証の種類の選択に応じて、次の 2 つの方法のいずれかでこのアクセスを許可できます。

Microsoft Entra 認証でマネージド ID を使用する場合は、コンテナーのストレージ BLOB データ共同作成者 RBAC ロールを、Azure SQL 論理サーバーまたは Azure SQL マネージドインスタンスのマネージド ID に割り当てます。

Note

拡張イベントセッションでのマネージド ID の使用はプレビュー段階です。
シークレットベースの認証を使用する場合は、コンテナーの SAS トークンを作成します。

この認証の種類を使用するには、[ストレージアカウントキーへのアクセスを許可する] オプションを有効にする必要があります。詳細については、Azure ストレージアカウントの共有キーによる認可の禁止に関するページを参照してください。

マネージド ID を使用してアクセスを許可する

Azure portal 内で、Azure SQL 論理サーバーまたは Azure SQL マネージドインスタンスの [ID] ページに移動し、マネージド ID が割り当てられていることを確認します。詳細については、「Azure SQL 用 Microsoft Entra のマネージド ID」を参照してください。
Azure portal 内で、イベントデータを格納するストレージコンテナーに移動します。 [アクセス制御 (IAM)] ページ上で [追加] を選択し、[ストレージ BLOB データ共同作成者] RBAC ロールを論理サーバーまたは SQL マネージドインスタンスのマネージド ID に割り当てます。

論理サーバーまたは SQL マネージドインスタンスのシステム割り当てマネージド ID が有効になっている場合は、その ID にロールを割り当てます。システム割り当て ID が無効になっているものの、1 つ以上のユーザー割り当て ID がある場合は、プライマリ ID として指定されたユーザー割り当て ID にロールを割り当てます。

詳細は、「BLOB データにアクセスするための Azure ロールを割り当てる」を参照してください。
特定のコンテナー URL のマネージド ID を使用し、Azure Storage に対して認証するようにデータベースエンジンに指示する資格情報を作成します。
- SQL Database
- SQL Managed Instance
データベーススコープの資格情報を作成します。 SSMS や ADS などのクライアントツールを使用して、新しいクエリウィンドウを開き、イベントセッションを作成するデータベースに接続し、次の T-SQL バッチを貼り付けます。 master データベースではなく、ユーザーデータベースに接続されていることを確認します。

Note

次の 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.windows.net/<container-name>'
          )
    DROP DATABASE SCOPED CREDENTIAL [https://<storage-account-name>.blob.core.windows.net/<container-name>];

/*
When using managed identity, the credential does not contain a secret
*/
CREATE DATABASE SCOPED CREDENTIAL [https://<storage-account-name>.blob.core.windows.net/<container-name>]
WITH IDENTITY = 'MANAGED IDENTITY';
```
サーバースコープの資格情報を作成します。 SSMS や ADS などのクライアントツールを使用して、新しいクエリウィンドウを開き、イベントセッションを作成するマネージドインスタンスの master データベースに接続し、次の T-SQL バッチを貼り付けます。

Note

次の T-SQL バッチを実行するには、CONTROL の master データベースロールのメンバー、およびマネージドインスタンスの db_owner サーバーロールのメンバーが持つ master データベースの 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.windows.net/<container-name>'
          )
    DROP CREDENTIAL [https://<storage-account-name>.blob.core.windows.net/<container-name>];

/*
When using managed identity, the credential does not contain a secret
*/
CREATE CREDENTIAL [https://<storage-account-name>.blob.core.windows.net/<container-name>]
WITH IDENTITY = 'MANAGED IDENTITY';
```
このバッチを実行する前に、次の変更を行います。
- https://<storage-account-name>.blob.core.windows.net/<container-name> が発生した 3 つのケース全てにおいて、<storage-account-name> はストレージアカウント名に置き換えられ、<container-name> はコンテナー名に置き換えられます。

SAS トークンを使用してアクセスを許可する

Azure portal 内で、作成したストレージアカウントとコンテナーに移動します。コンテナーを選択し、[設定>共有アクセストークン] に移動します。

SAS トークンは次の要件を満たす必要があります。
- Read、Write、Delete、List に設定されたアクセス許可。
- 開始時刻と有効期限は、そのイベントセッションの有効期間を包含する必要があります。作成する SAS トークンは、この時間間隔内でのみ機能します。
- IP アドレスの制限がない。
[SAS トークンおよび URL を生成] ボタンを選択します。 SAS トークンは、[BLOB SAS トークン] ボックスにあります。これをコピーして、次の手順で使用できます。

重要

SAS トークンは、このコンテナーへの読み取りと書き込みのアクセスを提供します。パスワードやその他のシークレットと同様に扱います。
SAS トークンを格納するための資格情報を作成します。
- SQL Database
- SQL Managed Instance
SAS トークンをデータベーススコープの資格情報に格納します。 SSMS や ADS などのクライアントツールを使用して、新しいクエリウィンドウを開き、イベントセッションを作成するデータベースに接続し、次の T-SQL バッチを貼り付けます。 master データベースではなく、ユーザーデータベースに接続されていることを確認します。

Note

次の 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.windows.net/<container-name>'
          )
    DROP DATABASE SCOPED CREDENTIAL [https://<storage-account-name>.blob.core.windows.net/<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.windows.net/<container-name>]
WITH IDENTITY = 'SHARED ACCESS SIGNATURE',
    SECRET = '<sas-token>';
```
このバッチを実行する前に、次の変更を行います:
- https://<storage-account-name>.blob.core.windows.net/<container-name> が発生した 3 つのケース全てにおいて、<storage-account-name> はストレージアカウント名に置き換えられ、<container-name> はコンテナー名に置き換えられます。
- SECRET 句の中で、<sas-token> を前の手順の中でコピーした SAS トークンに置き換えます。
SAS トークンをサーバースコープの資格情報に格納します。 SSMS や ADS などのクライアントツールを使用して、新しいクエリウィンドウを開き、イベントセッションを作成するマネージドインスタンスの master データベースに接続し、次の T-SQL バッチを貼り付けます。

Note

次の T-SQL バッチを実行するには、CONTROL の master データベースロールのメンバー、およびマネージドインスタンスの db_owner サーバーロールのメンバーが持つ master データベースの 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.windows.net/<container-name>'
          )
    DROP CREDENTIAL [https://<storage-account-name>.blob.core.windows.net/<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.windows.net/<container-name>]
WITH IDENTITY = 'SHARED ACCESS SIGNATURE',
    SECRET = '<sas-token>';
```
このバッチを実行する前に、次の変更を行います:
- CREATE MASTER KEY ステートメントでは、 <password> をマスターキーを保護する実際のパスワードに置き換えます。詳細については、「CREATE MASTER KEY」を参照してください。
- https://<storage-account-name>.blob.core.windows.net/<container-name> が発生した 3 つのケース全てにおいて、<storage-account-name> はストレージアカウント名に置き換えられ、<container-name> はコンテナー名に置き換えられます。
- SECRET 句の中で、<sas-token> を前の手順の中でコピーした SAS トークンに置き換えます。

イベントセッションを作成、開始、停止する

資格情報が作成されたら、イベントセッションを作成できます。資格情報の作成とは異なり、イベントセッションの作成に CONTROL アクセス許可は必要ありません。資格情報が作成されたら、より制限されたアクセス許可がある場合でも、イベントセッションを作成できます。特定の必要なアクセス許可については、「アクセス許可」を参照してください。

SSMS で新しいイベントセッションを作成するには、[拡張イベント] ノードを展開します。このノードは、Azure SQL データベースのデータベースフォルダーの下にあり、Azure SQL Managed Instance の管理フォルダーの下にあります。 [セッション] フォルダーを右クリックし、[新しいセッション...] を選択します。[全般] ページで、セッションの名前を入力します。この例では、example-session です。 [イベント] ページで、セッションに追加する 1 つ以上のイベントを選択します。この例では、sql_batch_starting イベントが選択されています。

sql_batch_starting イベントが選択されているイベント選択ページを示す [新しいセッション SSMS] ダイアログのスクリーンショット。

[データストレージ] ページで、ターゲットの種類として event_file を選択し、[ストレージ URL] ボックスにストレージコンテナーの URL を貼り付けます。この URL の末尾にスラッシュ (/) を入力し、その後にファイル (BLOB) 名を入力します。この例では、BLOB 名は example-session.xel、URL 全体は https://<storage-account-name>.blob.core.windows.net/<container-name>/example-session.xel です。

Note

SQL Managed Instance の場合は、[データストレージ] ページにストレージコンテナーの URL を貼り付ける代わりに、[スクリプト] ボタンを使用してセッションの T-SQL スクリプトを作成します。次の SQL Managed Instance の例のように、filename 引数の値としてコンテナー URL を指定し、スクリプトを実行してセッションを作成します。

[新しいセッション SSMS] ダイアログのスクリーンショット。データストレージの選択ページで event_file ターゲットが選択され、入力されたストレージ URL が表示されています。

セッションが構成されたので、[スクリプト] ボタンを選択して、後で保存するセッションの T-SQL スクリプトを作成できます。このセッション例のスクリプトを次に示します:

SQL Database
SQL Managed Instance

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.windows.net/<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.windows.net/<container-name>/example-session.xel')
GO

[OK] を選択してセッションを作成します。

オブジェクトエクスプローラーで、セッション フォルダーを展開して、作成したイベントセッションを表示します。既定では、セッションは作成時に開始されません。セッションを開始するには、セッション名を右クリックし、[セッションの開始] を選択します。セッションが実行されたら、同様に [セッションの停止] を選択して、後で停止できます。

このデータベースまたはマネージドインスタンス内で T-SQL バッチが実行されると、セッションはストレージコンテナー内の example-session.xel BLOB にイベントを書き込みます。

セッションを停止するには、オブジェクトエクスプローラーでセッションを右クリックし、[セッションの停止] を選択します。

イベントデータの表示

SQL Server Management Studio (SSMS) イベントビューアー UI でイベントデータを表示できます。ここでは、フィルターと集計を使用してキャプチャしたデータを分析できます。 SSMS でイベントビューアーを使用する方法の詳細については、「SSMS でのイベントデータの表示」を参照してください。

Azure Storage から xel ファイルをダウンロードする

ヒント

SSMS v19.2 以降を使用する場合は、このセクションの説明に従って xel ファイルをダウンロードする必要はありません。これらのバージョンでは、SSMS は各セッションの xel ファイルを Azure Storage から直接読み取ります。詳細については、「Azure SQL での拡張イベントの改善」に関するブログを参照してください。

ストレージコンテナーからセッションの xel BLOB をダウンロードし、ローカルファイルとして保存します。 Azure portal で、使用したストレージアカウントを見つけ、[データストレージ] で [コンテナー] を選択し、イベントセッション用に作成したコンテナーを選択します。セッションの BLOB には、名前の最初の部分としてセッション名があり、サフィックスは数値です。省略記号 (...) を選択して BLOB のコンテキストメニューを表示し、[ダウンロード] を選択します。

Azure Storage Explorer をインストールすると、1 回の操作で複数の xel BLOB をダウンロードできます。

xel ファイルがダウンロードされたら、SSMS で開きます。 SSMS メインメニューの [ファイル] に移動し、[開く] を選択します。 1 つの xel ファイルがある場合は、[ファイル...] を選択し、ダウンロードしたファイルを参照します。同じイベントセッションによって生成された複数の xel ファイル (ロールオーバーファイルと呼ばれます) がある場合は、[拡張イベントファイルのマージ...] ダイアログを使用して、イベントビューアーでそれらのすべてを開くことができます。

T-SQL を使用してイベントデータを表示する

T-SQL を使用してイベントセッションデータを読み取る場合は、sys.fn_xe_file_target_read_file() 関数を使用します。イベントセッションが作成されたものとは異なるデータベースまたはマネージドインスタンス内でこの関数を使用するには、イベントデータ BLOB を含むストレージコンテナー上のデータベースエンジンへのアクセスを許可します。

詳細なチュートリアルについては、「SSMS でのイベントセッションの作成」を参照してください。

次の方法で共有

Azure Storage で event_file ターゲットとのイベントセッションを作成する

ストレージアカウントとコンテナーの作成