Cibles pour les événements étendus

Article
07/12/2024

S’applique à : SQL Server base de données Azure SQL Azure SQL Managed Instance

Cet article explique quand et comment utiliser les cibles Extended Events. Pour chaque cible, cet article vous explique :

Ses capacités en termes de collecte et de génération de rapports sur les données envoyées par les événements
Ses paramètres, sauf si le paramètre est explicite

Le tableau suivant décrit la disponibilité de chaque type de cible dans différents moteurs de base de données.

Type cible	SQL Server	Azure SQL Database	Azure SQL Managed Instance
etw_classic_sync_target	Oui	No	Non
event_counter	Oui	Oui	Oui
event_file	Oui	Oui	Oui
event_stream	Oui	Oui	Oui
histogram	Oui	Oui	Oui
pair_matching	Oui	No	Non
ring_buffer	Oui	Oui	Oui

Prérequis

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.
avoir installé une version récente de SQL Server Management Studio (SSMS). Pour plus d’informations, consultez la page Télécharger SQL Server Management Studio (SSMS).
dans SSMS, savoir comment utiliser Explorateur d’objets pour cliquer avec le bouton droit sur le nœud cible sous votre session d’événement, pour une visualisation facile des données de sortie.

Paramètres, actions et champs

L’instruction CREATE EVENT SESSION est au cœur d’Extended Events. Pour rédiger l’instruction, vous devez :

les événements que vous souhaitez ajouter à la session
les champs associés à l’événement sélectionné
Les paramètres associés à chaque cible que vous souhaitez ajouter aux sessions

Les instructions SELECT, qui renvoient de telles listes à partir de vues système sont disponibles à la copie depuis l’article suivant dans sa section C :

Utilisation de SELECT et JOIN dans les vues système pour les événements étendus dans SQL Server
- C.4 Champs SELECT pour un événement.
- C.6 Paramètres SELECT pour une cible.
- C.3 Actions SELECT.

Vous pouvez voir les paramètres, les champs et les actions utilisés dans le contexte d’une instruction réelle CREATE EVENT SESSION, à partir de la section B2 (perspective T-SQL).

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, tandis que la plupart des cibles procèdent de manière asynchrone.

Remarque

Azure SQL Managed Instance et base de données Azure SQL ne prennent pas en charge la cible etw_classic_sync_target. En guise d’alternative, utilisez la cible event_file avec des objets blob stockés dans Stockage Azure.

Cible event_counter

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

Contrairement à la plupart des autres cibles :

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

Exemple de sortie capturée par la cible event_counter

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

Vient ensuite l’instruction CREATE EVENT SESSION qui a renvoyé les résultats précédents. Pour cet exemple, le champ package0.counter a été utilisé dans le prédicat de clause WHERE pour arrêter le comptage après que le compte atteigne 4.

CREATE EVENT SESSION [event_counter_1]
    ON SERVER
    ADD EVENT sqlserver.checkpoint_begin   -- Test by issuing CHECKPOINT; statements.
    (
        WHERE [package0].[counter] <= 4   -- A predicate filter.
    )
    ADD TARGET package0.event_counter
    WITH
    (
        MAX_MEMORY = 4096 KB,
        MAX_DISPATCH_LATENCY = 3 SECONDS
    );

event_file target

La cible event_file écrit la sortie de session d’événements de la mémoire tampon 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 en tant que préfixe auquel un entier long basé sur une date-heure est ajouté suivi de l’extension xel.

Remarque

Azure SQL Managed Instance et la base de données Azure SQL ne font que des blobs dans Azure Storage en tant que valeur du paramètre filename.

Pour obtenir un exemple de code event_file utilisable avec SQL Database ou SQL Managed Instance, consultez Code cible du fichier d’événements pour Extended Events dans SQL Database.

CREATE EVENT SESSION avec cible event_file

Voici un exemple de CREATE EVENT SESSION avec une clause ADD TARGET qui ajoute une cible event_file.

CREATE EVENT SESSION [locks_acq_rel_eventfile_22]
    ON SERVER
    ADD EVENT sqlserver.lock_acquired
    (
        SET
            collect_database_name=(1),
            collect_resource_description=(1)
        ACTION (sqlserver.sql_text,sqlserver.transaction_id)
        WHERE
        (
            [database_name]=N'InMemTest2'
            AND
            [object_id]=370100359
        )
    ),
    ADD EVENT sqlserver.lock_released
    (
        SET
            collect_database_name=1,
            collect_resource_description=1
        ACTION(sqlserver.sql_text,sqlserver.transaction_id)
        WHERE
        (
            [database_name]=N'InMemTest2'
            AND
            [object_id]=370100359
        )
    )
    ADD TARGET package0.event_counter,
    ADD TARGET package0.event_file
    (
        SET filename=N'C:\temp\locks_acq_rel_eventfile_22-.xel'
    )
    WITH
    (
        MAX_MEMORY=4096 KB,
        MAX_DISPATCH_LATENCY=10 SECONDS
    );

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 fonction sys.fn_xe_file_target_read_file vous permet de représenter le contenu d’un fichier xel sous la forme d’un jeu de lignes relationnel.

Pour SQL Server 2016 et versions ultérieures, utilisez une instruction SELECT similaire à l’exemple suivant.

SELECT f.*
--,CAST(f.event_data AS XML)  AS [Event-Data-Cast-To-XML]  -- Optional
FROM sys.fn_xe_file_target_read_file(
    'C:\temp\locks_acq_rel_eventfile_22-*.xel', NULL, NULL, NULL)  AS f;

Pour SQL Server 2014 et versions ultérieures, utilisez une instruction SELECT similaire à l’exemple suivant. Après SQL Server 2014, les fichiers xem ne sont plus utilisés.

SELECT f.*
--,CAST(f.event_data AS XML)  AS [Event-Data-Cast-To-XML]  -- Optional
FROM sys.fn_xe_file_target_read_file(
    'C:\temp\locks_acq_rel_eventfile_22-*.xel', 'C:\temp\metafile.xem', NULL, NULL) AS f;

Dans ces deux exemples, le caractère générique * est utilisé pour lire tous les fichiers xel qui commencent par le préfixe spécifié.

Dans la base de données Azure SQL, vous pouvez appeler la fonction sys.fn_xe_file_target_read_file() après avoir créé des informations d’identification délimitées à la base de données contenant un jeton SAP avec les autorisations Read et List sur le conteneur avec les objets blob xel :

/*
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 URI of the blob container.
*/
IF EXISTS (
    SELECT *
    FROM sys.database_credentials
    WHERE name = 'https://exampleaccount4xe.blob.core.windows.net/extended-events-container'
)
DROP DATABASE SCOPED CREDENTIAL [https://exampleaccount4xe.blob.core.windows.net/extended-events-container];

/*
The secret is the SAS token for the container. The Read and List permissions are set.
*/
CREATE DATABASE SCOPED CREDENTIAL [https://exampleaccount4xe.blob.core.windows.net/extended-events-container]
    WITH IDENTITY = 'SHARED ACCESS SIGNATURE',
        SECRET = 'sp=rl&st=2023-10-09T22:12:54Z&se=2023-10-10T06:12:54Z&spr=https&sv=2022-11-02&sr=c&sig=REDACTED';

/*
Return event session data
*/
SELECT f.*
--,CAST(f.event_data AS XML)  AS [Event-Data-Cast-To-XML]  -- Optional
FROM sys.fn_xe_file_target_read_file('https://exampleaccount4xe.blob.core.windows.net/extended-events-container/event-session-1', DEFAULT, DEFAULT, DEFAULT) AS f;

Dans Azure SQL Managed Instance, vous pouvez appeler la fonction sys.fn_xe_file_target_read_file() après avoir créé des informations d’identification serveur contenant un jeton SAP avec les autorisations Read et List sur le conteneur avec les objets blob xel :

IF NOT EXISTS (
    SELECT 1
    FROM sys.symmetric_keys
    WHERE name = '##MS_DatabaseMasterKey##'
)
CREATE MASTER KEY ENCRYPTION BY PASSWORD = 'REDACTED';

/*
(Re-)create a database scoped credential.
The name of the credential must match the URI of the blob container.
*/
IF EXISTS (
    SELECT *
    FROM sys.credentials
    WHERE name = 'https://exampleaccount4xe.blob.core.windows.net/extended-events-container'
)
DROP CREDENTIAL [https://exampleaccount4xe.blob.core.windows.net/extended-events-container];

/*
The secret is the SAS token for the container. The Read and List permissions are set.
*/
CREATE CREDENTIAL [https://exampleaccount4xe.blob.core.windows.net/extended-events-container]
    WITH IDENTITY = 'SHARED ACCESS SIGNATURE',
        SECRET = 'sp=rl&st=2023-10-09T22:12:54Z&se=2023-10-10T06:12:54Z&spr=https&sv=2022-11-02&sr=c&sig=REDACTED';

/*
Return event session data
*/
SELECT f.*
--,CAST(f.event_data AS XML)  AS [Event-Data-Cast-To-XML]  -- Optional
FROM sys.fn_xe_file_target_read_file('https://exampleaccount4xe.blob.core.windows.net/extended-events-container/event-session-1', DEFAULT, DEFAULT, DEFAULT) AS f;

Conseil

Si vous spécifiez un préfixe de nom d’objet blob au lieu du nom d’objet blob complet dans le premier argument de sys.fn_xe_file_target_read_file(), la fonction retourne les données de tous les objets blob du conteneur qui correspondent au préfixe. Cela vous permet de récupérer des données à partir de tous les fichiers de substitution d’une session d’événements donnée sans utiliser le caractère générique *, qui n’est pas pris en charge par Stockage Azure.

Les exemples Azure SQL précédents omettent l’extension xel pour lire tous les fichiers de substitution d’une session nommée event-session-1.

Données stockées dans la cible event_file

Il s’agit d’un exemple de données retournées de sys.fn_xe_file_target_read_file dans SQL Server 2016 (13.x) et versions ultérieures.

module_guid                            package_guid                           object_name     event_data                                                                                                                                                                                                                                                                                          file_name                                                      file_offset
-----------                            ------------                           -----------     ----------                                                                                                                                                                                                                                                                                          ---------                                                      -----------
D5149520-6282-11DE-8A39-0800200C9A66   03FDA7D0-91BA-45F8-9875-8B6DD0B8E9F2   lock_acquired   <event name="lock_acquired" package="sqlserver" timestamp="2016-08-07T20:13:35.827Z"><action name="transaction_id" package="sqlserver"><value>39194</value></action><action name="sql_text" package="sqlserver"><value><![CDATA[  select top 1 * from dbo.T_Target;  ]]></value></action></event>   C:\temp\locks_acq_rel_eventfile_22-_0_131150744126230000.xel   11776
D5149520-6282-11DE-8A39-0800200C9A66   03FDA7D0-91BA-45F8-9875-8B6DD0B8E9F2   lock_released   <event name="lock_released" package="sqlserver" timestamp="2016-08-07T20:13:35.832Z"><action name="transaction_id" package="sqlserver"><value>39194</value></action><action name="sql_text" package="sqlserver"><value><![CDATA[  select top 1 * from dbo.T_Target;  ]]></value></action></event>   C:\temp\locks_acq_rel_eventfile_22-_0_131150744126230000.xel   11776

Cible d’histogramme

La cible histogram peut :

compter les occurrences de plusieurs éléments séparément
compter les occurrences de différents types d’éléments :
- Champs de l’événement
- Actions

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

Le paramètre source_type est la clé permettant de contrôler la cible d’histogramme :

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.

Le paramètre slots par défaut est 256. Si vous attribuez une autre valeur, la valeur est arrondie à la puissance de 2 la plus proche. Par exemple, slots=59 serait arrondie à 64. Le nombre maximum d’emplacements d’histogramme pour une cible histogram est 16384.

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 se produit lors de l’affectation d’événements à des emplacements. 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 Extended Events, en utilisant histogram comme cible et en la regroupant par object_id, pour collecter l’exécution de la procédure stockée.
Vous exécutez la procédure stockée A. Ensuite, vous exécutez la procédure stockée B.

Si la fonction de hachage renvoie la même valeur pour le object_id des deux procédures stockées, l’histogramme indique que la procédure stockée A est exécutée deux fois et que la procédure stockée 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.

Cible d’histogramme avec une action

Dans sa clause ADD TARGET ... (SET ...), l’instruction suivante CREATE EVENT SESSION spécifie l’attribution de paramètre cible source_type=1. Cela signifie que la cible d’histogramme suit une action.

Dans l’exemple présent, la clause ADD EVENT ... (ACTION ...) se produit pour offrir une seule action à choisir, à savoir sqlos.system_thread_id. Dans la clause ADD TARGET ... (SET ...), nous voyons l’affectation source=N'sqlos.system_thread_id'.

Remarque

Il n’est pas possible d’ajouter plus d’une cible du même type par session d’événements. Cela inclut la cible histogram. Il n’est également pas possible d’avoir plus d’une source (champ action/événement) par cible histogram. Par conséquent, une nouvelle session d’événement est requise pour suivre toutes les actions supplémentaires ou les champs d’événement dans une cible histogram distincte.

CREATE EVENT SESSION [histogram_lockacquired]
    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
        );

Les données suivantes ont été capturées. Les valeurs de la colonne value sont des valeurs system_thread_id. Par exemple, un total de 236 verrous ont été effectués sous le thread 6540.

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

Utilisez l’instruction SELECT pour découvrir les actions disponibles

L’instruction C.3 SELECT peut rechercher les actions que le système met à votre disposition afin que vous puissiez les spécifier sur votre instruction CREATE EVENT SESSION. Dans la clause WHERE, il vous faudrait tout d’abord modifier le filtre o.name LIKE pour refléter les actions qui vous intéressent.

Ensuite, vient un exemple d’ensemble de lignes renvoyé par SELECT C.3. L’action system_thread_id s’affiche à la deuxième ligne.

Package-Name   Action-Name                 Action-Description
------------   -----------                 ------------------
package0       collect_current_thread_id   Collect the current Windows thread ID
sqlos          system_thread_id            Collect current system thread ID
sqlserver      create_dump_all_threads     Create mini dump including all threads
sqlserver      create_dump_single_thread   Create mini dump for the current thread

Cible d’histogramme avec un champ d’événement

L’exemple suivant définit source_type=0. La valeur affectée à source est un champ d’événement.

CREATE EVENT SESSION [histogram_checkpoint_dbid]
    ON SERVER
    ADD EVENT  sqlserver.checkpoint_begin
    ADD TARGET package0.histogram
    (
    SET
        filtering_event_name = N'sqlserver.checkpoint_begin',
        source               = N'database_id',
        source_type          = 0
    );

Les données suivantes ont été capturées par la cible histogram. Les données montrent que la base de données avec ID 5 a connu 7 événements checkpoint_begin.

value   count
-----   -----
5       7
7       4
6       3

Utilisez l’instruction SELECT pour découvrir les champs disponibles sur l’événement choisi

L’instruction SELECT C.4 suivante montre les champs d’événement que vous pouvez choisir. Il vous faut tout d’abord modifier le filtre o.name LIKE pour qu’il soit le nom d’événement choisi.

L’ensemble de lignes suivant a été renvoyé par SELECT C.4. L’ensemble de lignes montre que database_id est le seul champ sur l’événement checkpoint_begin pouvant fournir des valeurs pour la cible histogram.

Package-Name   Event-Name         Field-Name   Field-Description
------------   ----------         ----------   -----------------
sqlserver      checkpoint_begin   database_id  NULL
sqlserver      checkpoint_end     database_id  NULL

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, cela peut poser problème lorsqu’un événement lock_acquired se produit, mais qu’aucun événement lock_released correspondant ne suit en temps voulu.

Le système ne met pas automatiquement en correspondance les événements de début et de fin. C’est vous qui expliquez la correspondance au système dans l’instruction CREATE EVENT SESSION. Lorsqu’un événement de début et de fin sont mis en correspondance, la paire est ignorée pour se concentrer sur les événements de début sans correspondance.

Rechercher de champs pouvant être mis en correspondance pour la paire d’événements de début et de fin

À l’aide de C.4 SELECT, nous voyons dans l’ensemble de lignes suivant que 16 champs environ sont associés à l’événement lock_acquired. L’ensemble de lignes affiché ici a été fractionné manuellement pour indiquer les champs mis en correspondance de notre exemple. Pour certains champs tels que duration, la tentative de correspondance est sans signification.

Package-Name   Event-Name   Field-Name               Field-Description
------------   ----------   ----------               -----------------
sqlserver   lock_acquired   database_name            NULL
sqlserver   lock_acquired   mode                     NULL
sqlserver   lock_acquired   resource_0               The ID of the locked object, when lock_resource_type is OBJECT.
sqlserver   lock_acquired   resource_1               NULL
sqlserver   lock_acquired   resource_2               The ID of the lock partition, when lock_resource_type is OBJECT, and resource_1 is 0.
sqlserver   lock_acquired   transaction_id           NULL

sqlserver   lock_acquired   associated_object_id     The ID of the object that requested the lock that was acquired.
sqlserver   lock_acquired   database_id              NULL
sqlserver   lock_acquired   duration                 The time (in microseconds) between when the lock was requested and when it was canceled.
sqlserver   lock_acquired   lockspace_nest_id        NULL
sqlserver   lock_acquired   lockspace_sub_id         NULL
sqlserver   lock_acquired   lockspace_workspace_id   NULL
sqlserver   lock_acquired   object_id                The ID of the locked object, when lock_resource_type is OBJECT. For other lock resource types it will be 0
sqlserver   lock_acquired   owner_type               NULL
sqlserver   lock_acquired   resource_description     The description of the lock resource. The description depends on the type of lock. This is the same value as the resource_description column in the sys.dm_tran_locks view.
sqlserver   lock_acquired   resource_type            NULL

Un exemple de la cible pair_matching

L’instruction suivante CREATE EVENT SESSION spécifie deux événements et deux cibles. La cible pair_matching spécifie deux ensembles de champs afin de faire correspondre les événements par 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.

Pour affiner les résultats, nous avons tout d’abord sélectionné de sys.objects pour rechercher le object_id de la table test. Nous avons ajouté un filtre pour cet ID d’objet dans la clause ADD EVENT ... (WHERE ...).

CREATE EVENT SESSION [pair_matching_lock_a_r_33]
    ON SERVER
    ADD EVENT sqlserver.lock_acquired
    (
        SET
            collect_database_name = 1,
            collect_resource_description = 1
        ACTION (sqlserver.transaction_id)
        WHERE
        (
            [database_name] = 'InMemTest2'
            AND
            [object_id] = 370100359
        )
    ),
    ADD EVENT sqlserver.lock_released
    (
        SET
            collect_database_name = 1,
            collect_resource_description = 1
        ACTION (sqlserver.transaction_id)
        WHERE
        (
            [database_name] = 'InMemTest2'
            AND
            [object_id] = 370100359
        )
    )
    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 tester la session de l’événement, nous avons délibérément empêché la libération de deux verrous acquis. Nous avons effectué cela en réalisant les étapes T-SQL suivantes :

BEGIN TRANSACTION.
UPDATE MyTable....
Inutile de émettre un COMMIT TRANSACTION, jusqu’à ce que nous ayons examiné les cibles.
Plus tard après le test, nous avons émis un COMMIT TRANSACTION.

La cible simple event_counter a donné les lignes de sortie suivantes. Étant donné que 52-50=2, la sortie implique que nous voyons 2 événements lock_acquired non jumelés lorsque nous examinons la sortie à partir de la cible pair-matching.

package_name   event_name      count
------------   ----------      -----
sqlserver      lock_acquired   52
sqlserver      lock_released   50

La cible simple pair_matching a donné la sortie suivante. Comme indiqué par la sortie event_counter, nous voyons en effet les deux lignes lock_acquired. Le fait de voir ces lignes signifie que ces deux événements lock_acquired ne sont pas appariés.

package_name   event_name      timestamp                     database_name   duration   mode   object_id   owner_type   resource_0   resource_1   resource_2   resource_description   resource_type   transaction_id
------------   ----------      ---------                     -------------   --------   ----   ---------   ----------   ----------   ----------   ----------   --------------------   -------------   --------------
sqlserver      lock_acquired   2016-08-05 12:45:47.9980000   InMemTest2      0          S      370100359   Transaction  370100359    3            0            [INDEX_OPERATION]      OBJECT          34126
sqlserver      lock_acquired   2016-08-05 12:45:47.9980000   InMemTest2      0          IX     370100359   Transaction  370100359    0            0                                   OBJECT          34126

Les lignes des événements non souhaités lock_acquired peuvent inclure le texte T-SQL fourni par l’action sqlserver.sql_text. Cela capture la requête qui a acquis les verrous.

Cible ring_buffer

La cible ring_buffer est pratique pour une collection d’événements rapide et simple en mémoire uniquement. Lorsque vous arrêtez la session d’événements, la sortie stockée est ignorée.

Dans cette section, nous montrons également comment vous pouvez utiliser XQuery pour convertir la représentation XML du contenu du tampon en anneau en un jeu de lignes relationnel plus lisible.

Conseil

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

Par défaut, MAX_MEMORY pour une cible ring_buffer n’est pas limité dans SQL Server et est limité à 32 Mo dans la base de données Azure SQL et Azure SQL Managed Instance.

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">

CREATE EVENT SESSION avec une cible ring_buffer

Voici un exemple de création d’une session d’événements avec une cible ring_buffer. Dans cet exemple, le paramètre MAX_MEMORY apparaît deux fois : une fois pour définir la mémoire cible ring_buffer sur 1024 Ko, et une fois pour définir la mémoire tampon de session d’événements sur 2 Mo.

CREATE EVENT SESSION [ring_buffer_lock_acquired_4]
    ON SERVER
    ADD EVENT sqlserver.lock_acquired
    (
        SET collect_resource_description=(1)
        ACTION(sqlserver.database_name)
        WHERE
        (
            [object_id]=(370100359)  -- ID of MyTable
            AND
            sqlserver.database_name='InMemTest2'
        )
    )
    ADD TARGET package0.ring_buffer
    (
        SET MAX_EVENTS_LIMIT = 98,
            MAX_MEMORY = 1024
    )
    WITH
    (
        MAX_MEMORY = 2 MB,
        MAX_DISPATCH_LATENCY = 3 SECONDS
    );

Sortie XML reçue pour lock_acquired par la cible ring_buffer

Lorsqu’une instruction SELECT est récupérée, le contenu d’une mémoire tampon en anneau est présenté sous la forme d’un document XML. Un exemple est montré ensuite. Toutefois, pour des raisons de concision, tous les deux éléments <event> ont été supprimés. En outre, dans chaque <event>, une poignée d’éléments <data> ont également été supprimés.

<RingBufferTarget truncated="0" processingTime="0" totalEventsProcessed="6" eventCount="6" droppedCount="0" memoryUsed="1032">
  <event name="lock_acquired" package="sqlserver" timestamp="2016-08-05T23:59:53.987Z">
    <data name="mode">
      <type name="lock_mode" package="sqlserver"></type>
      <value>1</value>
      <text><![CDATA[SCH_S]]></text>
    </data>
    <data name="transaction_id">
      <type name="int64" package="package0"></type>
      <value>111030</value>
    </data>
    <data name="database_id">
      <type name="uint32" package="package0"></type>
      <value>5</value>
    </data>
    <data name="resource_0">
      <type name="uint32" package="package0"></type>
      <value>370100359</value>
    </data>
    <data name="resource_1">
      <type name="uint32" package="package0"></type>
      <value>0</value>
    </data>
    <data name="resource_2">
      <type name="uint32" package="package0"></type>
      <value>0</value>
    </data>
    <data name="database_name">
      <type name="unicode_string" package="package0"></type>
      <value><![CDATA[]]></value>
    </data>
    <action name="database_name" package="sqlserver">
      <type name="unicode_string" package="package0"></type>
      <value><![CDATA[InMemTest2]]></value>
    </action>
  </event>
  <event name="lock_acquired" package="sqlserver" timestamp="2016-08-05T23:59:56.012Z">
    <data name="mode">
      <type name="lock_mode" package="sqlserver"></type>
      <value>1</value>
      <text><![CDATA[SCH_S]]></text>
    </data>
    <data name="transaction_id">
      <type name="int64" package="package0"></type>
      <value>111039</value>
    </data>
    <data name="database_id">
      <type name="uint32" package="package0"></type>
      <value>5</value>
    </data>
    <data name="resource_0">
      <type name="uint32" package="package0"></type>
      <value>370100359</value>
    </data>
    <data name="resource_1">
      <type name="uint32" package="package0"></type>
      <value>0</value>
    </data>
    <data name="resource_2">
      <type name="uint32" package="package0"></type>
      <value>0</value>
    </data>
    <data name="database_name">
      <type name="unicode_string" package="package0"></type>
      <value><![CDATA[]]></value>
    </data>
    <action name="database_name" package="sqlserver">
      <type name="unicode_string" package="package0"></type>
      <value><![CDATA[InMemTest2]]></value>
    </action>
  </event>
</RingBufferTarget>

Pour afficher le code XML précédent, vous pouvez émettre l’instruction SELECT suivante lorsque la session d’événements est active. Les données XML sont récupérées à partir de la vue système sys.dm_xe_session_targets.

SELECT CAST(LocksAcquired.TargetXml AS XML) AS RBufXml
INTO #XmlAsTable
FROM (
    SELECT CAST(t.target_data AS XML) AS TargetXml
    FROM sys.dm_xe_session_targets AS t
    INNER JOIN sys.dm_xe_sessions AS s
        ON s.address = t.event_session_address
    WHERE t.target_name = 'ring_buffer'
        AND s.name = 'ring_buffer_lock_acquired_4'
) AS LocksAcquired;

SELECT *
FROM #XmlAsTable;

XQuery pour afficher le code XML sous forme d’un ensemble de lignes

Pour afficher le code XML précédent sous forme d’un ensemble de lignes relationnel, continuez à partir de l’instruction SELECT précédente en émettant l’instruction T-SQL suivante. Les lignes commentées expliquent chaque utilisation de XQuery.

SELECT
    -- (A)
    ObjectLocks.value('(@timestamp)[1]', 'datetime') AS [OccurredDtTm],
    -- (B)
    ObjectLocks.value('(data[@name="mode"]/text)[1]', 'nvarchar(32)') AS [Mode],
    -- (C)
    ObjectLocks.value('(data[@name="transaction_id"]/value)[1]', 'bigint') AS [TxnId],
    -- (D)
    ObjectLocks.value('(action[@name="database_name" and @package="sqlserver"]/value)[1]', 'nvarchar(128)') AS [DatabaseName]
FROM #XmlAsTable
CROSS APPLY
    -- (E)
    TargetDateAsXml.nodes('/RingBufferTarget/event[@name="lock_acquired"]') AS T(ObjectLocks);

Notes de XQuery issues de l’instruction SELECT précédente

(A)

Valeur de timestamp= attribute, sur l’élément <event>.
La construction '(...)[1]' garantit le renvoi d’une seule valeur par itération, comme il s’agit d’une limitation requise de la méthode XQuery .value() de la variable et des colonnes de type de données XML.

(B)

La valeur interne de l’élément <text>, dans un élément <data>, dont le nom = attribut est égal à mode.

(C)

La valeur interne des éléments <value>, dans un élément <data>, dont le nom = attribut est égal à transaction_id.

(D)

<event> contient <action>.
<action> ayant name= attribut égal à database_name, et package= attribut égal à sqlserver (pas package0), obtient la valeur interne de l’élément <value>.

(E)

CROSS APPLY entraîne la répétition du traitement de chaque élément <event> dont attribute name est égal à lock_acquired.
Cela s’applique au code XML renvoyé par la clause FROM précédente.

Sortie de XQuery SELECT

Ensuite, vient l’ensemble de lignes généré par l’instruction T-SQL précédente, qui inclut XQuery.

OccurredDtTm              Mode    DatabaseName
------------              ----    ------------
2016-08-05 23:59:53.987   SCH_S   InMemTest2
2016-08-05 23:59:56.013   SCH_S   InMemTest2

cible event_stream

La cible event_stream peut être utilisée uniquement dans des programmes .NET écrits dans des langages tels que C#. C# et d’autres développeurs .NET peuvent accéder à un flux d’événements via des classes .NET Framework dans l’espace de noms Microsoft.SqlServer.XEvents.Linq. Cette cible ne peut pas être utilisée dans T-SQL.

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.

Partage via

Cibles pour les événements étendus

Prérequis

Paramètres, actions et champs

Cible etw_classic_sync_target

Cible event_counter

Exemple de sortie capturée par la cible event_counter

event_file target

CREATE EVENT SESSION avec cible event_file

Function sys.fn_xe_file_target_read_file()

Données stockées dans la cible event_file

Cible d’histogramme

Cible d’histogramme avec une action

Utilisez l’instruction SELECT pour découvrir les actions disponibles

Cible d’histogramme avec un champ d’événement

Utilisez l’instruction SELECT pour découvrir les champs disponibles sur l’événement choisi

Cible pair_matching

Rechercher de champs pouvant être mis en correspondance pour la paire d’événements de début et de fin

Un exemple de la cible pair_matching

Cible ring_buffer

CREATE EVENT SESSION avec une cible ring_buffer

Sortie XML reçue pour lock_acquired par la cible ring_buffer

XQuery pour afficher le code XML sous forme d’un ensemble de lignes

Notes de XQuery issues de l’instruction SELECT précédente

Sortie de XQuery SELECT

cible event_stream

Espaces de noms XEvent

Commentaires

Ressources supplémentaires