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

  • Article

S’applique à : Azure SQL Database Azure 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 approprié à utiliser.
  2. Créez un conteneur dans ce compte de stockage.
  3. Accordez au moteur de base de données l’accès requis au conteneur à l’aide d’une attribution de rôle RBAC ou d’un jeton SAP.
  4. Créez des informations d’identification dans la base de données ou l’instance managée où vous créez la session d’événements.
  5. Créez, démarrez et utilisez 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 avez créés. Vous les utiliserez dans les étapes suivantes.

Accorder l’accès au conteneur

Pour lire et écrire des données d’événement, le moteur de base de données nécessite un accès spécifique au conteneur. Vous pouvez accorder cet accès de deux façons, en fonction de votre choix de type d’authentification :

  • Si vous utilisez l’identité managée avec l’authentification Microsoft Entra, vous affectez le rôle RBAC Contributeur aux données Blob du stockage pour le conteneur à l’identité managée du serveur logique Azure SQL ou de l’instance Azure SQL Managed Instance.

    Remarque

    L’utilisation de l’identité managée avec des sessions d’événements étendues est en préversion.

  • Si vous utilisez l’authentification basée sur des secrets, vous créez un jeton SAS pour le conteneur.

    Pour utiliser ce type d’authentification, l’option Autoriser l’accès à la clé de compte de stockage doit être activée. Pour plus d'informations, consultez Empêcher l'autorisation avec clé partagée pour un compte de stockage Azure.

Accorder l’accès à l’aide de l’identité managée

  1. Dans le portail Azure, accédez à la page Identité de votre serveur logique Azure SQL ou de votre instance SQL Managed Instance, puis vérifiez qu’une identité managée est affectée. Pour plus d’informations, consultez Identités managées dans Microsoft Entra pour Azure SQL.

  2. Dans le portail Azure, accédez au conteneur de stockage dans lequel vous souhaitez stocker les données d’événement. Dans la page Contrôle d’accès (IAM), sélectionnez Ajouter pour affecter le rôle RBAC Contributeur aux données blob de stockage à l’identité managée du serveur logique ou de l’instance SQL Managed Instance.

    Si le serveur logique ou l’instance SQL Managed Instance a activé son identité managée affectée par le système, attribuez le rôle à cette identité. Si l’identité affectée par le système est désactivée, mais qu’il existe une ou plusieurs identités affectées par l’utilisateur, attribuez le rôle à l’identité affectée par l’utilisateur désignée comme identité principale.

    Pour plus d’informations, consultez Attribuer un rôle Azure pour l’accès aux données d’objet blob.

  3. Créez des informations d’identification pour indiquer au moteur de base de données de s’authentifier auprès du stockage Azure à l’aide de l’identité managée pour une URL de conteneur spécifique.

    Créez des informations d’identification incluses dans l’étendue de 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.

    /*
(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';

    Avant d’exécuter ce lot, apportez la modification suivante :

    • Dans les trois occurrences de https://<storage-account-name>.blob.core.windows.net/<container-name>, remplacez <storage-account-name> par le nom de votre compte de stockage et remplacez <container-name> par le nom de votre conteneur.

Accorder l’accès à l’aide d’un jeton SAP

  1. Dans le portail Azure, accédez au compte de stockage et le conteneur que vous avez créé. Sélectionnez le conteneur, puis accédez à Paramètres > Jetons d’accès partagé.

    Le jeton SAP doit répondre aux exigences suivantes :

    • Autorisations définies sur Read, Write, Delete, List.
    • L’heure de début et l’heure d’expiration doivent englober la durée de vie de la session d’événements. Le jeton SAS que vous créez fonctionne uniquement dans cet intervalle de temps.
    • Il ne doit avoir aucune restriction des adresses IP.

    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.

    Capture d’écran de l’écran Jetons d’accès partagé pour un conteneur Stockage Azure, avec un jeton SAS généré pour un exemple de conteneur.

  2. Créez des informations d’identification pour stocker le jeton SAP.

    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://<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>';

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

    • Dans les trois occurrences de https://<storage-account-name>.blob.core.windows.net/<container-name>, remplacez <storage-account-name> par le nom de votre compte de stockage et remplacez <container-name> par le nom de votre conteneur.
    • Dans la clause SECRET, remplacez <sas-token> par le jeton SAP que vous avez copié à l’étape précédente.

Créez, démarrez et arrêtez une session d’événements

Une fois les informations d’identification créées, vous pouvez créer la session d’événements. Contrairement à la création des informations d’identification, la création d’une session d’événements ne nécessite pas l’autorisation CONTROL. Une fois les informations d’identification créées, vous pouvez créer des sessions d’événements même si vous disposez d’autorisations plus restreintes. 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é.

Capture d’écran de la boîte de dialogue Nouvelle session SSMS montrant la page de sélection d’événements avec l’événement sql_batch_starting sélectionné.

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://<storage-account-name>.blob.core.windows.net/<container-name>/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.

Capture d’écran de la boîte de dialogue Nouvelle session SSMS montrant la page de sélection de stockage de données avec une cible event_file sélectionnée et une URL de stockage entrée.

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://<storage-account-name>.blob.core.windows.net/<container-name>/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 cette instance managée, la session écrit des événements dans l’objet blob example-session.xel dans le conteneur de stockage.

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 managée différente de celle où la session d’événements est créée, accordez l’accès au moteur de base de données sur le conteneur de stockage avec les objets blob de données d’événement.

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

Contenu connexe