Créer une session avec une cible event_file dans Stockage Azure

  • Article

S’applique à : Azure SQL DatabaseAzure SQL Managed Instance

Les étapes générales de cette procédure pas à pas sont les suivantes :

  1. Créez un compte de Stockage Azure ou recherchez un compte existant à utiliser
  2. Créer un conteneur dans le compte de stockage
  3. Créer un jeton SAS avec l’accès requis pour ce conteneur
  4. Créer un identifiant pour stocker le jeton SAS dans la base de données ou l'instance gérée où vous créez la session d'événement
  5. Créer, démarrer et utiliser une session d’événements

Créer un compte de stockage et un conteneur

Pour plus d’informations sur la création d’un compte de Stockage Azure, consultez Créer un compte de stockage. Vous allez apprendre à créer un compte de stockage à l’aide de Portail Azure, PowerShell, Azure SQL, d’un modèle ARM ou d’un modèle Bicep.

Nous vous recommandons d’utiliser un compte utilisateur ayant les caractéristiques suivantes :

Vous devrez ensuite créer un conteneur dans le compte de stockage à l’aide du portail Azure. Vous pouvez également créer un conteneur en utilisant PowerShell ou Azure CLI.

Notez les noms du compte de stockage et du conteneur que vous utilisez.

Créez un jeton SAS

La Moteur de base de données en cours d’exécution de la session d’événements a besoin d’un accès spécifique au conteneur de stockage. Vous accordez cet accès en créant un jeton SAS pour le conteneur. Cet outil doit répondre aux exigences suivantes :

  • Disposer des autorisations rwl (Read, Write, List)
  • Disposer de l’heure de début et de l’heure d’expiration qui englobent la durée de vie de la session d’événements
  • Il ne doit pas avoir de restriction des adresses IP.

Sur le portail Azure, recherchez le compte de stockage et le conteneur que vous avez créé. Sélectionnez le conteneur, puis accédez à Paramètres > Jetons d’accès partagé. Réglez les autorisations sur Read, Write, List et réglez la date et l’heure de début et d’expiration. Le jeton SAS que vous créez fonctionne uniquement dans cet intervalle de temps.

Sélectionnez le bouton Générer une URL et un jeton SAS. Le jeton SAS se trouve dans la zone de jeton SAS d’objet blob. Vous pouvez le copier pour l’utiliser à l’étape suivante.

Important

Le jeton SAS fournit un accès en lecture et en écriture à ce conteneur. Traitez-le comme vous traitez un mot de passe ou tout autre secret.

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

Créer un identifiant pour stocker le jeton SAS

Dans la base de données Azure SQL, vous utilisez un identifiant de base de données pour stocker le jeton SAS. Dans Azure SQL Managed Instance, vous utilisez un identifiant à l’échelle du serveur.

Stockez le jeton SAS dans un identifiant géré par la base de données. À l’aide d’un outil client tel que SSMS ou ADS, ouvrez une nouvelle fenêtre Requête, connectez-vous à la base de données où vous créez la session d’événements et collez le lot T-SQL suivant. Vérifiez que vous êtes connecté à votre base de données utilisateur et non à la base de données master.

Remarque

L’exécution du lot T-SQL suivant nécessite l’autorisation de la base de données CONTROL, qui est détenue par le propriétaire de base de données (dbo), par les membres du db_owner rôle de base de données et par l’administrateur du serveur logique.

/*
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.windows.net/xe-example-container'
          )
    DROP DATABASE SCOPED CREDENTIAL [https://exampleaccount4xe.blob.core.windows.net/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.windows.net/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';

Avant d’exécuter ce lot, apportez les modifications suivantes :

  • Dans les trois occurrences de https://exampleaccount4xe.blob.core.windows.net/xe-example-container, remplacez exampleaccount4xe par le nom de votre compte de stockage et remplacez xe-example-container par le nom de votre conteneur.
  • Remplacez la chaîne entière entre les guillemets simples de la clause SECRET par le jeton SAS que vous avez copié à l’étape précédente.

Créer, démarrer et arrêter une session d’événements

Une fois les informations d’identification avec le jeton SAS créé, vous pouvez créer la session d’événements. La création d’une session d’événements ne nécessite pas l’autorisation CONTROL . Si l’identifiant avec le jeton SAS correct existe déjà, vous pouvez créer des sessions d’événements même si vous disposez d’un ensemble plus restreint d’autorisations. Consultez les autorisations pour connaître les autorisations spécifiques nécessaires.

Pour créer une nouvelle session d’événements dans SSMS, développez le nœud Événements étendus. Ce nœud se trouve sous le dossier de base de données dans la base de données Azure SQL et sous le dossier Gestion dans Azure SQL Managed Instance. Cliquez avec le bouton droit sur le dossier Sessions, puis sélectionnez Nouvelle session.... Dans la page Général, entrez un nom pour la session, qui se trouve example-session dans cet exemple. Dans la page Événements, sélectionnez un ou plusieurs événements à ajouter à la session. Dans cet exemple, l’événement sql_batch_starting est sélectionné.

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

Dans la page Stockage de données, sélectionnez event_file comme type de cible, puis collez l’URL du conteneur de stockage dans la zone URL de Stockage. Tapez une barre oblique (/) à la fin de cette URL, suivie du nom du fichier (blob). Dans notre exemple, le nom de l’objet blob est example-session.xel, et l’URL entière est https://exampleaccount4xe.blob.core.windows.net/xe-example-container/example-session.xel.

Remarque

Pour SQL Managed Instance, au lieu de coller l’URL du conteneur de stockage sur la page Stockage des données, utilisez le bouton Script pour créer un script T-SQL de la session. Spécifiez l’URL du conteneur comme valeur de l’argument filename, comme dans l’exemple SQL Managed Instance ci-dessous, puis exécutez le script pour créer la session.

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

Maintenant que la session est configurée, vous pouvez sélectionner le bouton Script pour créer un script T-SQL de la session, pour l’enregistrer ultérieurement. Voici le script de notre exemple de session :

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

Sélectionnez OK pour créer l’utilisateur.

Dans l’Explorateur d’objets, développez le dossier Sessions pour voir la session d’événements que vous avez créée. Par défaut, la session n’est pas démarrée lors de sa création. Pour démarrer la session, cliquez avec le bouton droit sur le nom de la session, puis sélectionnez Démarrer la session. Vous pouvez l’arrêter ultérieurement en sélectionnant de la même façon Arrêter la session, une fois la session en cours d’exécution.

À mesure que les lots T-SQL sont exécutés dans cette base de données ou l’instance gérée, la session écrit des événements dans l’objet blob example-session.xel dans le conteneur de stockage xe-example-container.

Pour arrêter la session, cliquez dessus avec le bouton droit dans l’Explorateur d’objets, puis sélectionnez Arrêter la session.

Afficher les données d’événement

Vous pouvez afficher les données d’événement dans l’interface utilisateur de l’observateur d’événements SQL Server Management Studio (SSMS), où vous pouvez utiliser des filtres et des agrégations pour analyser les données que vous avez capturées. Pour plus d’informations sur l’utilisation de l’observateur d’événements dans SSMS, consultez Afficher les données d’événement dans SSMS.

Télécharger des fichiers xel à partir du stockage Azure

Conseil

Si vous utilisez SSMS v19.2 ou version ultérieure, vous n’avez pas besoin de télécharger xel fichiers comme décrit dans cette section. Dans ces versions, SSMS lit les fichiers xel de chaque session directement à partir du stockage Azure. Pour plus d’informations, consultez le blog Amélioration des événements étendus dans le blog Azure SQL.

Téléchargez l’objet blob xel pour la session à partir du conteneur de stockage et enregistrez-le en tant que fichier local. Dans Portail Azure, recherchez le compte de stockage que vous avez utilisé, sélectionnez Conteneurs sous Stockage de données, puis sélectionnez le conteneur que vous avez créé pour votre session d’événements. L’objet blob de la session a le nom de session comme première partie de son nom, avec un suffixe numérique. Sélectionnez les points de suspension (...) pour afficher le menu contextuel de l’objet blob, puis sélectionnez Télécharger.

Vous pouvez installer Explorateur Stockage Azure pour télécharger plusieurs objets blob xel en une seule opération.

Une fois le fichier xel téléchargé, ouvrez-le dans SSMS. Dans le menu principal de SSMS, accédez à Fichier et sélectionnez Ouvrir. Si vous avez un seul fichier xel, sélectionnez Fichier... et accédez au fichier que vous avez téléchargé. Si vous avez plusieurs fichiers xel générés par la même session d’événements (appelées fichiers de substitution), vous pouvez utiliser la boîte de dialogue Fusionner les fichiers d’événements étendus... pour les ouvrir dans l’observateur d’événements.

Afficher les données d’événement à l’aide de T-SQL

Pour lire les données de session d’événements à l’aide de T-SQL, utilisez la fonction sys.fn_xe_file_target_read_file(). Pour utiliser cette fonction dans une base de données ou une instance gérée différente de celle où la session d’événements est créée, créer un identifiant pour donner au Moteur de base de données l’accès au conteneur de stockage avec les objets blob d’événements.

Pour obtenir une procédure pas à pas plus détaillée, consultez Créer une session d’événements dans SSMS.

Contenu connexe