Cibles des événements étendus

S’applique à :SQL Server Azure SQL Database Azure SQL Managed Instance Base de données SQL dans Microsoft Fabric

Cet article explique quand et comment utiliser les cibles Extended Events. Pour chaque cible, l’article décrit :

Ses capacités de collecte et de production de rapports de données d’événements
Exemples de sessions d’événements utilisant la cible

Le tableau suivant décrit la disponibilité de chaque type cible dans différentes plateformes SQL.

Type cible	Serveur SQL	Base de données Azure SQL et base de données SQL dans Fabric	Azure SQL Managed Instance (Instance gérée Azure SQL)
fichier_événement	Oui	Oui	Oui
ring_buffer	Oui	Oui	Oui
event_stream	Oui	Oui	Oui
histogramme	Oui	Oui	Oui
compteur_événements	Oui	Oui	Oui
pair_matching	Oui	Non	Non
etw_classic_sync_target	Oui	Non	Non

Sauf indication différente, les cibles traitent les données qu’elles reçoivent de manière asynchrone.

Pour tirer le meilleur parti de cet article, vous devez :

vous familiariser avec les bases d’Extended Events, comme décrit dans Démarrage rapide : Extended Events.
Utilisez une version récente de SQL Server Management Studio (SSMS).

fichier_événement cible

La event_file cible écrit la sortie de session d’événements à partir de mémoires tampons dans un fichier disque ou dans un objet blob dans Stockage Azure.

Vous spécifiez le paramètre filename dans la clause ADD TARGET. L’extension du fichier doit être xel.
Le nom de fichier que vous choisissez est utilisé par le système comme préfixe auquel une valeur numérique basée sur la date est ajoutée, suivie de l’extension xel .
Vous pouvez éventuellement spécifier le MAX_FILE_SIZE paramètre. Il définit la taille maximale en mégaoctets (Mo) vers laquelle le fichier peut croître avant la création d’un nouveau fichier.
Vous pouvez éventuellement spécifier l’option MAX_ROLLOVER_FILES permettant de choisir le nombre maximal de fichiers à conserver dans le système de fichiers en plus du fichier actif. La valeur par défaut est UNLIMITED. Lorsqu'il MAX_ROLLOVER_FILES est évalué, si le nombre de fichiers dépasse le paramètre MAX_ROLLOVER_FILES, les fichiers plus anciens sont supprimés.

Important

Selon les événements ajoutés à une session, les fichiers produits par la event_file cible peuvent contenir des données sensibles. Examinez attentivement le système de fichiers et partagez les autorisations sur le répertoire et les fichiers individuels .xel , y compris l’accès hérité, pour éviter d’accorder un accès en lecture inutile. Suivez le principe du privilège minimum. Pour réduire le risque de collecte de données sensibles par inadvertance, évitez les sessions d’événements longues si elles peuvent collecter des données sensibles.

Remarque

Azure SQL Database et Azure SQL Managed Instance prennent uniquement en charge les objets blob dans Stockage Azure comme valeur pour le paramètre filename. Pour obtenir un event_file exemple de code pour Azure SQL Database, SQL Database dans Fabric ou Azure SQL Managed Instance, consultez Créer une session d’événements avec une cible event_file dans Stockage Azure.

Créer une session d’événements avec event_file cible dans le système de fichiers local

Pour obtenir une procédure pas à pas pour créer une session d’événements à l’aide d’un event_file stockage de fichiers local, avec SSMS ou T-SQL, consultez Démarrage rapide : Événements étendus.

Créer une session d’événements avec event_file cible dans Stockage Azure

Pour obtenir une description détaillée de la création d’un compte de stockage dans Stockage Azure, consultez Créer un compte de stockage. Vous pouvez créer un compte de stockage à l’aide du portail Azure, de PowerShell, d’Azure SQL, d’un modèle ARM ou d’un modèle Bicep. Utilisez un compte qui :

Est un Standard general-purpose v2 compte.
Utilise le Hot blob.
Si vous utilisez SQL Server dans une machine virtuelle Azure (machine virtuelle Azure), le compte de stockage doit se trouver dans la même région Azure que votre machine virtuelle Azure.
L’espace de noms hiérarchique n’est pas activé.

Ensuite, créez un conteneur dans ce compte de stockage à l’aide du portail Azure. Vous pouvez également créer un conteneur à l’aide de PowerShell ou d’Azure CLI.

Notez les noms du compte de stockage et du conteneur que vous avez créés. Vous les utilisez dans les étapes suivantes.

Pour lire et écrire des données d’événement, le moteur de base de données nécessite un accès spécifique. Vous accordez cet accès différemment en fonction de votre choix de type d’authentification : identité managée ou authentification basée sur des secrets avec un jeton de signature d’accès partagé (SAP).

Pour s’authentifier auprès du stockage Azure, le moteur de base de données nécessite des informations d’identification au niveau du serveur ou des informations d’identification délimitées à la base de données, qui lui indique le type d’authentification à utiliser et fournit un secret pour l’authentification basée sur des secrets. La création de ces informations d’identification nécessite l’autorisation CONTROL de base de données.

Pour SQL Server et Azure SQL Managed Instance, cette autorisation est requise dans la master base de données. Par défaut, l’autorisation est détenue par les membres du db_owner rôle de base de données dans master, et par les membres du sysadmin rôle serveur sur l’instance. Pour Azure SQL Database et la base de données SQL dans Fabric, cette autorisation est détenue par le propriétaire de la 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.

Une fois les informations d’identification créées, les étapes restantes pour créer une session d’événements ne nécessitent pas l’autorisation CONTROL . Consultez Autorisations pour connaître les autorisations spécifiques nécessaires.

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

Si vous utilisez l'authentification Microsoft Entra avec une identité managée, vous attribuez le rôle RBAC Contributeur aux données Blob du stockage à l'identité managée utilisée par le moteur de base de données pour le conteneur. Pour plus d’informations, consultez les informations suivantes basées sur la plateforme SQL :

Une fois l’attribution de rôle RBAC en place, procédez comme suit :

Créez des informations d’identification à l’aide de T-SQL.

Avant d’exécuter le lot T-SQL suivant, 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. Assurez-vous qu'il n'y ait pas de slash final dans l'URL.
Créer des informations d’identification au niveau du serveur : (S’applique à SQL Server, Azure SQL Managed Instance)

À l’aide d’un outil client tel que SSMS, ouvrez une nouvelle fenêtre de requête, connectez-vous à master la base de données sur l’instance où vous souhaitez créer la session d’événements et collez le lot T-SQL suivant.
```
/* 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';
```
Créer des informations d’identification délimitées à la base de données : (S’applique à Azure SQL Database, Azure SQL Managed Instance, base de données SQL dans Fabric)

À l’aide d’un outil client tel que SSMS, ouvrez une nouvelle fenêtre de requête, connectez-vous à la base de données utilisateur 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.
```
/* 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';
```
Ensuite, suivez les étapes pour créer une session d’événements dans SSMS avec event_file cible dans Stockage Azure.

Accorder l’accès à l’aide d’un jeton de signature d’accès partagé (SAP)

Si vous utilisez l’authentification basée sur des secrets, vous créez un jeton de signature d’accès partagé (SAP) pour le conteneur. Pour utiliser ce type d’authentification, l’option Autoriser l’accès à la clé du compte de stockage doit être activée pour le compte de stockage. Pour plus d’informations, consultez Empêcher l’autorisation avec clé partagée pour un compte de stockage Azure.

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

Le jeton SAP doit répondre aux exigences suivantes :
- Autorisations définies sur Read, , WriteDelete, 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 SAP que vous créez fonctionne uniquement dans cet intervalle de temps.
- Pour Azure SQL Database, Azure SQL Managed Instance et SQL Database dans Fabric, le jeton SAP ne doit pas avoir de restrictions d’adresse IP.
Sélectionnez le bouton Générer le jeton SAP et l’URL . Le jeton SAS se trouve dans la zone jeton SAS d’objet blob. Vous pouvez la copier pour l’utiliser à l’étape suivante.

Important

Le jeton SAP fournit un accès en lecture et en écriture à ce conteneur. Traitez-le comme vous traitez un mot de passe ou tout autre secret.
Créez des informations d’identification pour stocker le jeton SAP à l’aide de T-SQL.

Avant d’exécuter le lot T-SQL suivant, apportez ces modifications :
- Si vous créez des informations d’identification limitées au serveur et que vous utilisez l’instruction CREATE MASTER KEY , remplacez <password> par un mot de passe fort qui protège la clé principale. Pour plus d’informations, consultez CREATE MASTER KEY.
- 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 SECRET clause, remplacez <sas-token> par le jeton SAP que vous avez copié à l’étape précédente.
Créer des informations d’identification au niveau du serveur : (S’applique à SQL Server, Azure SQL Managed Instance)

À l’aide d’un outil client tel que SSMS, ouvrez une nouvelle fenêtre de requête, connectez-la à la master base de données sur l’instance où vous créez la session d’événements, puis collez le lot T-SQL suivant.
```
/* 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>'

/* 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. */
CREATE CREDENTIAL
    [https://<storage-account-name>.blob.core.windows.net/<container-name>]
WITH IDENTITY = 'SHARED ACCESS SIGNATURE',
    SECRET = '<sas-token>';
```
Créer des informations d’identification délimitées à la base de données : (S’applique à Azure SQL Database, Azure SQL Managed Instance, base de données SQL dans Fabric)

À l’aide d’un outil client tel que SSMS, ouvrez une nouvelle fenêtre de 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.
```
/* 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. */
CREATE DATABASE SCOPED CREDENTIAL
    [https://<storage-account-name>.blob.core.windows.net/<container-name>]
WITH IDENTITY = 'SHARED ACCESS SIGNATURE',
    SECRET = '<sas-token>';
```
Ensuite, suivez les étapes de la section suivante pour créer une session d’événements dans SSMS avec event_file cible dans Stockage Azure.

Créer une session d’événements dans SSMS avec la cible event_file dans Azure Storage

Une fois que les informations d’identification fournissant l’accès au conteneur de stockage sont 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 Autorisations pour connaître les autorisations spécifiques nécessaires.

Pour créer une session d’événements dans SSMS :

Pour SQL Server et Azure SQL Managed Instance, développez le nœud Événements étendus sous le dossier Gestion . Pour Azure SQL Database et la base de données SQL dans Fabric, développez le nœud Événements étendus sous la base de données.
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 correspond example-session à l’exemple de code suivant.
Dans la page Événements , sélectionnez un ou plusieurs événements à ajouter à la session. Par exemple, vous pouvez sélectionner l’événement sql_batch_starting .
Dans la page Stockage des données , sélectionnez event_file le type cible. 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). Par exemple : https://<storage-account-name>.blob.core.windows.net/<container-name>/example-session.xel.
Maintenant que la session est configurée, vous pouvez éventuellement sélectionner le bouton Script pour créer un script T-SQL de la session, pour l’enregistrer ultérieurement.
Cliquez sur OK pour créer la session.
Dans l’Explorateur d’objets, développez le dossier Sessions pour afficher la session d’événement 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 Arrêter la session une fois la session en cours d’exécution.

À mesure que les lots T-SQL sont exécutés, la session écrit les sql_batch_starting événements dans l’objet example-session.xel blob dans le conteneur de stockage.

Remarque

Pour SQL Managed Instance, au lieu de coller l’URL du conteneur de stockage sur la page Stockage des données, cliquez sur 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 et exécutez le script pour créer la session.

Créer une session d'événements avec la cible event_file sur Azure Storage dans T-SQL

Voici un exemple de clause CREATE EVENT SESSIONADD TARGET qui ajoute une cible basée sur event_file stockage Azure.

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

Pour utiliser cet exemple dans Azure SQL Database ou sql Database dans Fabric, remplacez ON SERVER par ON DATABASE.

Résoudre les problèmes de sessions d’événements avec la cible event_file dans Azure Storage

La liste suivante contient des erreurs que vous pouvez rencontrer lors du démarrage d’une session d’événements étendue qui utilise stockage Azure, avec les explications possibles de l’erreur.

Le système d’exploitation a retourné l’erreur 5 : « L’accès est refusé ».
- Si vous utilisez l’authentification d’identité managée :
  - L’identité managée utilisée par le moteur de base de données n’a pas l’attribution de rôle RBAC requise. Pour plus d’informations, consultez Accorder l’accès à l’aide de l’identité managée.
  - Le pare-feu du compte de stockage est activé et une exception permettant d’autoriser les services Azure approuvés à accéder au compte de stockage est également activée, mais une Microsoft.Sql/servers instance de ressource pour le serveur logique n’a pas été ajoutée à la liste des instances de ressources auxquelles l’accès est accordé. Pour plus d’informations, voir Permettre l'accès à partir des instances de ressources Azure.
  - Si vous utilisez un périmètre de sécurité réseau en mode appliqué, la base de données et le compte de stockage ne se trouvent pas dans le même périmètre.
- Si vous utilisez l’authentification par jeton SAS :
  - Le pare-feu du compte de stockage est activé. Cela n’est pas pris en charge pour les sessions d’événements qui utilisent l’authentification par jeton SAP.
  - Le jeton SAP n’a pas d’autorisations suffisantes ou a expiré. Pour plus d’informations, consultez Accorder l’accès à l’aide d’un jeton SAP.
  - Si vous utilisez un périmètre de sécurité réseau en mode appliqué, les règles d’accès pour autoriser les communications sortantes illimitées de la base de données et les communications entrantes illimitées vers le compte de stockage ne sont pas en place.
Le système d’exploitation a retourné l’erreur 86 : « Le mot de passe réseau spécifié n’est pas correct. »
- Il n’existe pas d’informations d’identification délimitées à la base de données (pour Azure SQL Database) ou d’informations d’identification au niveau du serveur (pour Azure SQL Managed Instance ou SQL Server) avec le nom correspondant à l’URL du conteneur d’objets blob. Pour plus d’informations, consultez les exemples permettant d’accorder l’accès à l’aide d’une identité managée ou d’accorder l’accès à l’aide d’un jeton SAP.
- Le nom des informations d’identification se termine par une barre oblique (/). Le nom des informations d’identification, sans inclure la barre oblique de fin, doit se terminer par le nom du conteneur.
Le système d’exploitation a retourné l’erreur 3 : « Le système ne trouve pas le chemin spécifié. »
- Le conteneur spécifié dans l’URL du conteneur d’objets blob n’existe pas.
Le système d’exploitation a retourné l’erreur 13 : « Les données ne sont pas valides . »
- Il existe une stratégie d’immuabilité sur le conteneur blob. Le stockage immuable n’est pas pris en charge pour les sessions d’événements.
- Le compte de stockage a l’espace de noms hiérarchique activé. Les comptes de stockage avec espace de noms hiérarchique activé ne sont pas pris en charge pour les sessions d’événements.

Function sys.fn_xe_file_target_read_file()

La cible event_file stocke les données reçues dans un format binaire qui n’est pas lisible. La sys.fn_xe_file_target_read_file fonction vous permet de représenter le contenu d’un xel fichier en tant qu’ensemble de lignes relationnelles. Pour plus d’informations, y compris des exemples d’utilisation, consultez sys.fn_xe_file_target_read_file.

Cible ring_buffer

La ring_buffer cible est utile pour démarrer rapidement une session d'événement et collecter les données d'événement uniquement en mémoire. Lorsque la mémoire disponible dans la mémoire tampon en anneau est utilisée par les événements, les anciens événements sont ignorés. Lorsque vous arrêtez la session d’événements, toutes les sorties de session vers la ring_buffer cible sont également supprimées.

Vous consommez des données à partir d’une cible ring_buffer en la convertissant en XML, comme illustré dans l’exemple suivant. Pendant cette conversion, toutes les données qui ne tiennent pas dans un document XML de 4 Mo sont omises. Par conséquent, même si vous capturez davantage d’événements dans la mémoire tampon d’anneau à l’aide de valeurs MAX_MEMORY plus grandes (ou en laissant ce paramètre à sa valeur par défaut), vous ne pourrez peut-être pas les consommer en raison de la limite de 4 Mo sur la taille du document XML, compte tenu de la surcharge des marques XML et des chaînes Unicode.

Vous savez que le contenu de la mémoire tampon en anneau est omis lors de la conversion en XML si l’attribut truncated du document XML est défini sur 1, par exemple :

<RingBufferTarget truncated="1" processingTime="0" totalEventsProcessed="284" eventCount="284" droppedCount="0" memoryUsed="64139">

Conseil

Lors de l’ajout d’une ring_buffer cible, définissez son MAX_MEMORY paramètre sur 1 024 Ko ou moins. L’utilisation de valeurs plus importantes peut augmenter inutilement la consommation de mémoire.

Par défaut, MAX_MEMORY pour une ring_buffer cible n’est pas limitée dans SQL Server et est limitée à 32 Mo dans Azure SQL Database, Azure SQL Managed Instance et SQL Database dans Fabric.

Créer une session d’événements avec une cible ring_buffer

Voici un exemple de création d’une session d’événements avec une ring_buffer cible pour collecter les lock_acquired événements, limitant le nombre total d’événements dans la mémoire tampon circulaire à 100. Dans cet exemple, le MAX_MEMORY paramètre apparaît deux fois : une fois pour définir la ring_buffer mémoire cible sur 1 024 Ko, et une fois pour définir la mémoire tampon de session d’événements sur 2 Mo.

Pour utiliser cet exemple dans Azure SQL Database ou sql Database dans Fabric, remplacez ON SERVER par ON DATABASE.

CREATE EVENT SESSION ring_buffer_lock_acquired
ON SERVER
ADD EVENT sqlserver.lock_acquired
ADD TARGET package0.ring_buffer
(
SET MAX_EVENTS_LIMIT = 100,
    MAX_MEMORY = 1024
)
WITH
(
    MAX_MEMORY = 2 MB,
    MAX_DISPATCH_LATENCY = 3 SECONDS
);

Pour démarrer la session d’événements, exécutez l’instruction suivante :

ALTER EVENT SESSION ring_buffer_lock_acquired
ON SERVER
STATE = START;

Pour afficher les données d’événement collectées dans la mémoire tampon d’anneau dans SSMS, développez le nœud de session et sélectionnez la package0.ping_buffer cible. Les données sont affichées en XML.

Pour afficher les données d’événement d’une ring_buffer cible dans un ensemble de lignes relationnelles pendant que la session est active, vous utilisez des expressions XQuery pour convertir du code XML en données relationnelles. Par exemple:

;WITH
/* An XML document representing memory buffer contents */
RingBuffer AS
(
    SELECT CAST (xst.target_data AS XML) AS TargetData
    FROM sys.dm_xe_session_targets AS xst
         INNER JOIN sys.dm_xe_sessions AS xs
             ON xst.event_session_address = xs.address
    WHERE xs.name = N'ring_buffer_lock_acquired'
),
/* A row for each event in the buffer, represented as an XML fragment */
EventNode AS
(
    SELECT CAST (NodeData.query('.') AS XML) AS EventInfo
    FROM RingBuffer AS rb
    CROSS APPLY rb.TargetData.nodes('/RingBufferTarget/event') AS n(NodeData)
)

/* A relational rowset formed by using the XQuery value method */
SELECT EventInfo.value('(event/@timestamp)[1]','datetimeoffset') AS timestamp,
       EventInfo.value('(event/@name)[1]','sysname') AS event_name,
       EventInfo.value('(event/data/value)[1]','nvarchar(max)') AS sql_batch_text
FROM EventNode
ORDER BY timestamp DESC;

cible event_stream

La cible event_stream peut être utilisée uniquement dans des programmes .NET écrits dans des langages tels que C#. Les développeurs peuvent accéder à un flux d’événements par l’intermédiaire des classes du .NET Framework dans le namespace Microsoft.SqlServer.XEvents.Linq. Cette cible est implicitement présente dans n’importe quelle session d’événements. Il ne peut pas être ajouté à l’aide de T-SQL.

Pour plus d’informations, consultez sys.fn_MSxe_read_event_stream.

Si vous rencontrez l’erreur 25726, The event data stream was disconnected because there were too many outstanding events. To avoid this error either remove events or actions from your session or add a more restrictive predicate filter to your session. lors de la lecture de la cible event_stream, cela signifie que le flux d’événements s’est rempli de données plus rapidement que le client pourrait consommer les données. Cela provoque la déconnexion du moteur de base de données du flux d’événements pour éviter d’affecter les performances du moteur de base de données.

Cible d’histogramme

La histogram cible compte le nombre d’occurrences d’événements pour des valeurs distinctes dans un champ ou une action. Pour chaque valeur distincte, un compartiment de nombre distinct est utilisé. La histogram cible traite les données qu’elle reçoit de manière synchrone.

Le SOURCE_TYPE paramètre contrôle le comportement de la histogram cible :

SOURCE_TYPE = 0 : collecter des données pour un champ d’événement.
SOURCE_TYPE = 1 : collecter des données pour une action. Il s’agit de la valeur par défaut.

La valeur par défaut du SLOTS paramètre est 256. Si vous attribuez une autre valeur, la valeur est arrondie à la puissance de 2 la plus proche. Par exemple, SLOTS = 59 on arrondit jusqu’à 64. Le nombre maximal d’emplacements d’histogramme pour une histogram cible est de 16 384.

Lorsque vous utilisez histogram comme cible, vous pouvez parfois voir des résultats inattendus. Certains événements peuvent ne pas apparaître dans les emplacements attendus, tandis que d’autres emplacements peuvent afficher un nombre plus élevé d’événements que prévu. Cela peut se produire si une collision de hachage survient lors de l'attribution des événements à des créneaux. Bien que cela soit rare, si une collision de hachage se produit, un événement qui doit être compté dans un emplacement est compté dans un autre. Pour cette raison, vous devez prendre soin de supposer qu’un événement n’a pas eu lieu simplement parce que le nombre dans un emplacement particulier indique zéro.

Par exemple, considérez le scénario suivant :

Vous configurez une session Événements étendus, en utilisant histogram comme cible et en compartimentant les événements par object_id, pour collecter les statistiques d’exécution de procédures stockées.
Vous exécutez la procédure stockée A. Ensuite, vous exécutez la procédure stockée B.

Si la fonction de hachage retourne la même valeur pour les object_id des deux procédures stockées, l'histogramme montre que A est exécuté deux fois tandis que B n'apparaît pas.

Pour atténuer ce problème lorsque le nombre de valeurs distinctes est relativement petit, définissez le nombre d’emplacements d’histogrammes supérieurs au carré des valeurs distinctes attendues. Par exemple, si la cible histogram a sa SOURCE définie sur le champ d’événement table_name et qu’il existe 20 tables dans la base de données, alors 20*20 = 400. La puissance suivante de 2 supérieure à 400 est 512, qui est le nombre recommandé d’emplacements dans cet exemple.

Chaque histogram cible accepte les données d’une seule source (un champ d’événement ou une action) et ne contient qu’un seul histogramme. Il n’est pas possible d’ajouter plus d’une cible du même type par session d’événements. Il n’est pas possible d’avoir plus d’un type source par histogram cible. Par conséquent, une nouvelle session d’événements est nécessaire pour suivre différentes actions ou champs d’événement dans une cible distincte histogram .

Créer une session d’événements avec une cible d’histogramme

Voici un exemple de création d’une session d’événements avec une cible histogram.

Pour utiliser cet exemple dans Azure SQL Database ou sql Database dans Fabric, remplacez ON SERVER par ON DATABASE.

CREATE EVENT SESSION histogram_lock_acquired
ON SERVER
ADD EVENT sqlserver.lock_acquired
(
    ACTION (sqlos.system_thread_id)
)
ADD TARGET package0.histogram
(
    SET FILTERING_EVENT_NAME = N'sqlserver.lock_acquired',
        SLOTS = 16,
        SOURCE = N'sqlos.system_thread_id',
        SOURCE_TYPE = 1
);

Dans la ADD TARGET ... (SET ...) clause, le paramètre cible SOURCE_TYPE est défini sur 1, ce qui signifie que le histogram cible suit une action.

La ADD EVENT ... (ACTION ...) clause ajoute l’action sqlos.system_thread_id à l’événement. Le paramètre SOURCE est défini sur sqlos.system_thread_id pour que l'ID de thread système collecté par cette action soit utilisé comme source de données pour la cible histogram. La histogram cible de cet exemple compte le nombre d’événements lock_acquired pour chaque thread système qui acquiert des verrous pendant que la session est active.

Pour démarrer la session d’événements, exécutez l’instruction suivante :

ALTER EVENT SESSION histogram_lock_acquired
ON SERVER
STATE = START;

Pour afficher les données d’histogramme collectées dans SSMS, développez le nœud de session et sélectionnez la package0.histogram cible. Les données sont affichées dans une grille à deux colonnes. Chaque ligne représente un compartiment de valeurs distinctes et un nombre d’occurrences.

Voici comment les données capturées par la histogram cible dans cet exemple peuvent ressembler. Les valeurs de la colonne value sont des valeurs system_thread_id. Par exemple, un total de 236 verrous ont été acquis par le thread système 6540.

value   count
-----   -----
 6540     236
 9308      91
 9668      74
10144      49
 5244      44
 2396      28

Voici un exemple de lecture des données à partir d’une histogram cible avec T-SQL :

WITH histogram_target
AS (SELECT TRY_CAST (st.target_data AS XML) AS target_data
    FROM sys.dm_xe_sessions AS s
         INNER JOIN sys.dm_xe_session_targets AS st
             ON s.address = st.event_session_address
    WHERE s.name = 'event-session-name-placeholder'),
 histogram
AS (SELECT hb.slot.value('(@count)[1]', 'bigint') AS slot_count,
           hb.slot.value('(value/text())[1]', 'nvarchar(max)') AS slot_value
    FROM histogram_target AS ht
CROSS APPLY ht.target_data.nodes('/HistogramTarget/Slot') AS hb(slot))
SELECT slot_value,
       slot_count
FROM histogram;

Cible event_counter

La cible event_counter compte le nombre de fois où chaque événement spécifié se produit.

La event_counter cible n’a aucun paramètre et traite les données qu’elle reçoit de manière synchrone.

Créer une session d’événements avec une cible event_counter

Voici un exemple de création d’une session d’événements avec une cible event_counter. La session compte les quatre checkpoint_begin premiers événements, puis cesse de compter, car son prédicat limite le nombre d’événements envoyés aux cibles à quatre. Vous pouvez générer l’événement checkpoint_begin pour cet exemple en exécutant la CHECKPOINT commande.

Pour utiliser cet exemple dans Azure SQL Database ou sql Database dans Fabric, remplacez ON SERVER par ON DATABASE.

CREATE EVENT SESSION event_counter_checkpoint_begin
ON SERVER
ADD EVENT sqlserver.checkpoint_begin
(
    WHERE package0.counter <= 4
)
ADD TARGET package0.event_counter
WITH
(
    MAX_MEMORY = 4096 KB,
    MAX_DISPATCH_LATENCY = 3 SECONDS
);

Pour démarrer la session d’événements, exécutez l’instruction suivante :

ALTER EVENT SESSION event_counter_checkpoint_begin
ON SERVER
STATE = START;

Pour afficher les données collectées dans SSMS, développez le nœud de session et sélectionnez la package0.event_counter cible. Les données sont affichées dans une grille à trois colonnes. Chaque ligne représente un événement avec le nombre de ses occurrences.

Voici à quoi pourraient ressembler les données capturées par la event_counter cible dans cet exemple après quatre points de contrôle.

package_name   event_name         count
------------   ----------------   -----
sqlserver      checkpoint_begin   4

Cible pair_matching

La cible pair_matching vous permet de détecter les événements de début qui se produisent sans événement de fin correspondant. Par exemple, vous pouvez trouver un lock_acquired événement sans événement correspondant lock_released , ce qui peut indiquer qu’une transaction de longue durée contient des verrous.

Les événements étendus ne correspondent pas automatiquement aux événements de début et de fin. Au lieu de cela, vous définissez la logique correspondante dans la pair_matching spécification cible dans l’instruction CREATE EVENT SESSION . Lorsqu’un événement de début et de fin est mis en correspondance, la cible ignore la paire, mais conserve les événements de démarrage sans correspondance.

Créer une session d'événement avec une cible d'appariement de paires

Pour cet exemple, nous créons un exemple de table nommé T1, insérez trois lignes et obtenons la object_id valeur de cette table. Par souci de simplicité, nous créons la table dans la tempdb base de données dans cet exemple. Si vous utilisez une autre base de données, ajustez le nom de la base de données dans l’exemple de code T-SQL qui suit.

CREATE TABLE T1 (id INT PRIMARY KEY);

INSERT INTO T1 (id)
VALUES (1), (2), (3);

SELECT OBJECT_ID('T1') AS object_id;
-- object_id = 1029578706

La session d'événement suivante collecte deux événements, lock_acquired et lock_released. Il a également deux cibles. Il s’agit de la event_counter cible qui fournit le nombre d’occurrences pour chaque événement. L’autre est la pair_matching cible qui définit la logique permettant de faire correspondre l’événement de début lock_acquired et l’événement de fin lock_released en paires.

La séquence de champs délimités par des virgules affectées BEGIN_MATCHING_COLUMNS et END_MATCHING_COLUMNS doit être identique. Aucune tabulation ou saut de ligne n’est autorisé entre les champs mentionnés dans la valeur délimitée par une virgule, bien que les espaces soient autorisés.

Dans la définition de session d’événements, nous utilisons un prédicat d’événement pour collecter uniquement les événements de la base de données tempdb où l'object_id de l'événement correspond à l’ID d’objet de la table T1. Ajustez le prédicat dans la WHERE clause pour utiliser l’ID d’objet de votre table.

Pour utiliser cet exemple dans Azure SQL Database ou sql Database dans Fabric, remplacez ON SERVER par ON DATABASE.

CREATE EVENT SESSION pair_matching_lock_acquired_released
ON SERVER
ADD EVENT sqlserver.lock_acquired
(
    SET COLLECT_DATABASE_NAME = 1,
        COLLECT_RESOURCE_DESCRIPTION = 1
    ACTION (sqlserver.transaction_id)
    WHERE (database_name = 'tempdb'
           AND object_id = 1029578706)
),
ADD EVENT sqlserver.lock_released
(
    SET COLLECT_DATABASE_NAME = 1,
        COLLECT_RESOURCE_DESCRIPTION = 1
    ACTION (sqlserver.transaction_id)
    WHERE (database_name = 'tempdb'
           AND object_id = 1029578706)
)
ADD TARGET package0.event_counter,
ADD TARGET package0.pair_matching
(
    SET BEGIN_EVENT = N'sqlserver.lock_acquired',
        BEGIN_MATCHING_COLUMNS = N'resource_0, resource_1, resource_2, transaction_id, database_id',
        END_EVENT = N'sqlserver.lock_released',
        END_MATCHING_COLUMNS = N'resource_0, resource_1, resource_2, transaction_id, database_id',
        RESPOND_TO_MEMORY_PRESSURE = 1
)
WITH
(
    MAX_MEMORY = 8192 KB,
    MAX_DISPATCH_LATENCY = 15 SECONDS
);

Pour démarrer la session d’événements, exécutez l’instruction suivante :

ALTER EVENT SESSION pair_matching_lock_acquired_released
ON SERVER
STATE = START;

Démarrez une transaction qui met à jour la table T1, mais ne la validez pas et ne l'annulez pas. Cela garantit qu’il y a des verrous acquis mais pas libérés.

BEGIN TRANSACTION;
UPDATE T1
    SET id = id + 1;

Examinez la sortie de chaque cible de la pair_matching_lock_acquired_released session d’événements dans SSMS.

La event_counter cible génère la sortie suivante, indiquant qu’un verrou reste non libéré. Toutefois, cette cible n’affiche aucun détail de ce verrou.

package_name   event_name      count
------------   ----------      -----
sqlserver      lock_acquired   4
sqlserver      lock_released   3

La pair_matching cible a la sortie suivante, tronquée pour la concision. Comme suggéré par la event_counter sortie, nous voyons effectivement la ligne pour l'événement non apparié lock_acquired, avec plus de détails sur l'événement.

package_name  event_name    timestamp                     associated_object_id  database_id  database_name
------------  ------------  ---------                     -------------         -----------  -------------
sqlserver    lock_acquired   2025-10-01 20:06:07.1890000  1029578706            2            tempdb

Restaurez la transaction.

ROLLBACK;

Si vous ajoutez une action à un événement collecté par la pair_matching cible, les données d’action sont également collectées. Par exemple, vous pouvez inclure le texte T-SQL fourni par l’action sqlserver.sql_text avec l’événement. Dans cet exemple, il collecte la requête qui a acquis le verrou.

Cible etw_classic_sync_target

Dans SQL Server, Extended Events peut interagir avec le suivi d’événements pour Windows (ETW) pour surveiller l’activité système. Pour plus d’informations, consultez l’article suivant :

Cette cible ETW traite les données qu’elle reçoit de manière synchrone.

Rétroaction

Cette page a-t-elle été utile ?

Last updated on 2025-10-28

Partager via

Cibles des événements étendus

fichier_événement cible

Créer une session d’événements avec event_file cible dans le système de fichiers local

Créer une session d’événements avec event_file cible dans Stockage Azure

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

Accorder l’accès à l’aide d’un jeton de signature d’accès partagé (SAP)

Créer une session d’événements dans SSMS avec la cible event_file dans Azure Storage

Créer une session d'événements avec la cible event_file sur Azure Storage dans T-SQL

Résoudre les problèmes de sessions d’événements avec la cible event_file dans Azure Storage

Function sys.fn_xe_file_target_read_file()

Cible ring_buffer

Créer une session d’événements avec une cible ring_buffer

cible event_stream

Cible d’histogramme

Créer une session d’événements avec une cible d’histogramme

Cible event_counter

Créer une session d’événements avec une cible event_counter

Cible pair_matching

Créer une session d'événement avec une cible d'appariement de paires

Cible etw_classic_sync_target

Contenu connexe

Rétroaction

Ressources additionnelles