CREATE EVENT SESSION (Transact-SQL)

S’applique à : SQL Server Azure SQL Database Azure SQL Managed Instance

Crée une session d'événements étendus qui identifie la source des événements, les cibles de la session d'événements et les options de la session d'événements.

Conventions de la syntaxe Transact-SQL

Syntaxe

CREATE EVENT SESSION event_session_name
ON { SERVER | DATABASE }
{  
    <event_definition> [ ,...n]
    [ <event_target_definition> [ ,...n] ]
    [ WITH ( <event_session_options> [ ,...n] ) ]
}
;

<event_definition>::=
{
    ADD EVENT [event_module_guid].event_package_name.event_name
         [ ( {
                 [ SET { event_customizable_attribute = <value> [ ,...n] } ]
                 [ ACTION ( { [event_module_guid].event_package_name.action_name [ ,...n] } ) ]
                 [ WHERE <predicate_expression> ]
        } ) ]
}

<predicate_expression> ::=
{
    [ NOT ] <predicate_factor> | {( <predicate_expression> ) }
    [ { AND | OR } [ NOT ] { <predicate_factor> | ( <predicate_expression> ) } ]
    [ ,...n ]
}  
  
<predicate_factor>::=
{
    <predicate_leaf> | ( <predicate_expression> )
}

<predicate_leaf>::=
{
      <predicate_source_declaration> { = | < > | ! = | > | > = | < | < = } <value>
    | [event_module_guid].event_package_name.predicate_compare_name ( <predicate_source_declaration>, <value> )
}

<predicate_source_declaration>::=
{
    event_field_name | ( [event_module_guid].event_package_name.predicate_source_name )
}

<value>::=
{
    number | 'string'
}

<event_target_definition>::=
{
    ADD TARGET [event_module_guid].event_package_name.target_name
        [ ( SET { target_parameter_name = <value> [ ,...n] } ) ]
}

<event_session_options>::=
{  
    [    MAX_MEMORY = size [ KB | MB ] ]
    [ [,] EVENT_RETENTION_MODE = { ALLOW_SINGLE_EVENT_LOSS | ALLOW_MULTIPLE_EVENT_LOSS | NO_EVENT_LOSS } ]
    [ [,] MAX_DISPATCH_LATENCY = { seconds SECONDS | INFINITE } ]
    [ [,] MAX_EVENT_SIZE = size [ KB | MB ] ]
    [ [,] MEMORY_PARTITION_MODE = { NONE | PER_NODE | PER_CPU } ]
    [ [,] TRACK_CAUSALITY = { ON | OFF } ]
    [ [,] STARTUP_STATE = { ON | OFF } ]
}

Arguments

event_session_name

Nom défini par l'utilisateur de la session d'événements. event_session_name est alphanumérique, peut contenir jusqu’à 128 caractères, doit être unique dans une instance de SQL Server et doit respecter les règles applicables aux identificateurs.

ADD EVENT [ event_module_guid ].event_package_name.event_name

Événement à associer à la session d'événements, où :

• event_module_guid est le GUID du module qui contient l’événement.
• event_package_name est le package qui contient l’objet d’action.
• event_name est l’objet d’événement.

Les événements apparaissent dans la vue sys.dm_xe_objects en tant qu'object_type « événement ».

SET { event_customizable_attribute= <value> [ ,...n] }

Autorise les attributs personnalisables pour l'événement à définir. Les attributs personnalisables s’affichent dans la vue sys.dm_xe_object_columns sous la forme column_type « personnalisable » et object_name = event_name.

ACTION ( { [event_module_guid].event_package_name.action_name [ ,...n] })

Action à associer à la session d'événements, où :

• event_module_guid est le GUID du module qui contient l’événement.
• event_package_name est le package qui contient l’objet d’action.
• action_name est l’objet d’action.

Les événements apparaissent dans la vue sys.dm_xe_objects en tant qu'object_type « action ».

WHERE <predicate_expression>

Spécifie l'expression de prédicat utilisée pour déterminer si un événement doit être traité. Si <predicate_expression> est true, le traitement de l’événement par les actions et les cibles pour la session se poursuit. Si <predicate_expression> a la valeur false, l’événement est supprimé, ce qui évite d’effectuer des actions et un traitement cible supplémentaires. Les expressions de prédicat sont limitées à 3 000 caractères.

event_field_name Nom du champ d'événement qui identifie la source de prédicat.

[event_module_guid].event_package_name.predicate_source_name Nom de la source de prédicat globale, où :

• event_module_guid est le GUID du module qui contient l’événement.
• event_package_name est le package qui contient l’objet de prédicat.
• predicate_source_name est défini dans la vue sys.dm_xe_objects en tant que « pred_source » object_type.

[event_module_guid].event_package_name.predicate_compare_name Nom de l'objet de prédicat à associer à l'événement, où :

• event_module_guid est le GUID du module qui contient l’événement.
• event_package_name est le package qui contient l’objet de prédicat.
• predicate_compare_name est une source globale définie dans la vue sys.dm_xe_objects en tant que « pred_compare »object_type.

number Tout type numérique, dont decimal. Le manque de mémoire physique ou un nombre trop grand pour être représenté sous forme d'entier 64 bits sont les seules limitations.

'string' Chaîne ANSI ou Unicode, comme requis par la comparaison de prédicat. Aucune conversion implicite de type chaîne n'est effectuée pour les fonctions de comparaison de prédicat. La transmission d'un type incorrect provoque une erreur.

ADD TARGET [event_module_guid].event_package_name.target_name

Cible à associer à la session d'événements, où :

• event_module_guid est le GUID du module qui contient l’événement.
• event_package_name est le package qui contient l’objet d’action.
• target_name est la cible. Les cibles s'affichent dans la vue sys.dm_xe_objects en tant que « cible » object_type.

SET { target_parameter_name= <value> [, ...n] }

Définit un paramètre cible.

Pour afficher tous les paramètres cibles et leurs descriptions, exécutez la requête suivante, en remplaçant l’espace réservé par le target-name nom cible, tel que event_file, , ring_buffer, histogrametc.

SELECT name AS target_parameter_name,
       column_value AS default_value,
       description
FROM sys.dm_xe_object_columns
WHERE column_type = 'customizable'
      AND
      object_name = 'target-name';

Pour plus d’informations sur les types cibles, consultez Cibles pour les événements étendus dans SQL Server.

WITH ( <event_session_options> [ ,...n] )

Spécifie les options à utiliser avec la session d'événements.

MAX_MEMORY =size [ KB | MB ]

Spécifie la quantité de mémoire maximale à allouer à la session pour la mise en mémoire tampon d'événement. La valeur par défaut est 4 Mo. taille est un nombre entier et peut s'exprimer en kilo-octets (Ko) ou en mégaoctets (Mo). La quantité maximale ne peut pas dépasser 2 Go (moins de 2 048 Mo). Toutefois, l’utilisation de valeurs de mémoire en Go n’est pas recommandée.

EVENT_RETENTION_MODE = { ALLOW_SINGLE_EVENT_LOSS | ALLOW_MULTIPLE_EVENT_LOSS | NO_EVENT_LOSS }

Spécifie le mode de rétention des événements à utiliser pour gérer la perte d'événements.

ALLOW_SINGLE_EVENT_LOSS Il est possible de perdre un événement de la session. Un événement unique est abandonné uniquement lorsque toutes les mémoires tampons d'événements sont saturées. La perte d'un événement unique lorsque les mémoires tampons d'événements sont saturées permet d'obtenir des caractéristiques de performance SQL Server acceptables, tout en réduisant la perte de données du flux d'événements traité.

ALLOW_MULTIPLE_EVENT_LOSS Il est possible de perdre des mémoires tampons d'événements saturées contenant plusieurs événements. Le nombre d’événements perdus dépend de la taille de la mémoire allouée à la session, du partitionnement de la mémoire et de la taille des événements dans la mémoire tampon. Cette option atténue l'impact sur les performances du serveur lorsque les mémoires tampons d'événements sont rapidement remplies, mais il est possible de perdre un grand nombre d'événements de la session.

NO_EVENT_LOSS Aucune perte d'événements n'est autorisée. Cette option garantit que tous les événements déclenchés sont conservés. Cette option force toutes les tâches qui déclenchent des événements à attendre que de l'espace se libère dans une mémoire tampon d'événements. L’utilisation de NO_EVENT_LOSS peut entraîner des problèmes de performances détectables pendant que la session d’événements est active. Les connexions utilisateur peuvent se bloquer en attendant que les événements soient supprimés de la mémoire tampon.

MAX_DISPATCH_LATENCY = { seconds SECONDS | INFINITE }

Spécifie la durée pendant laquelle les événements sont mis en mémoire tampon avant d'être distribués aux cibles de la session d'événements. Elle est par défaut de 30 secondes.

seconds SECONDS Durée (en secondes) à attendre avant de commencer à vider les mémoires tampons vers les cibles. seconds est un nombre entier. La valeur de latence minimale est 1 seconde. Toutefois, la valeur 0 peut être utilisée pour spécifier une latence INFINITE.

INFINITE Vide les mémoires tampons vers les cibles uniquement lorsque les mémoires tampons sont saturées ou lors de la fermeture de la session d'événements.

MAX_EVENT_SIZE =size [ KB | MB ]

Spécifie la taille maximale autorisée pour les événements. MAX_EVENT_SIZE ne doit être défini que pour autoriser des événements uniques supérieurs à MAX_MEMORY ; la définition de la valeur inférieure à MAX_MEMORY génère une erreur. size est un nombre entier qui peut s’exprimer en kilo-octets (Ko) ou en mégaoctets (Mo). Si size est spécifié en kilo-octets, la taille minimale autorisée est 64 Ko. Lorsque MAX_EVENT_SIZE est défini, deux mémoires tampons de taille sont créées en plus de MAX_MEMORY, et la mémoire totale utilisée pour la mise en mémoire tampon d’événements est MAX_MEMORY + 2 * MAX_EVENT_SIZE.

MEMORY_PARTITION_MODE = { NONE | PER_NODE | PER_CPU }

Spécifie l'emplacement où les mémoires tampons d'événements sont créées.

NONE Un jeu unique de mémoires tampons est créé dans l'instance de SQL Server.

PER_NODE : un jeu de mémoires tampons est créé pour chaque nœud NUMA.

PER_CPU : un jeu de mémoires tampons est créé pour chaque UC.

TRACK_CAUSALITY = { ON | OFF }

Spécifie si la causalité est suivie ou non. Si cette option est activée, la causalité permet à des événements associés de différentes connexions au serveur d'être corrélés.

STARTUP_STATE = { ON | OFF }

Spécifie si cette session d'événements doit être lancée automatiquement au démarrage de SQL Server.

ON La session d'événements est lancée au démarrage.

OFF La session d’événements n’est pas démarrée au démarrage.

Notes

L’ordre de priorité des opérateurs logiques est NOT(la plus élevée), puis AND, puis OR.

autorisations

Sur SQL Server et SQL Managed Instance, nécessite l’autorisation CREATE ANY EVENT SESSION (introduite dans SQL Server 2022) ou ALTER ANY EVENT SESSION l’autorisation.

Sur SQL Database, requiert l’autorisation ALTER ANY DATABASE EVENT SESSION dans la base de données.

Exemples

Exemple SQL Server

L'exemple suivant montre comment créer une session d'événements appelée test_session. Cet exemple ajoute deux événements et utilise la cible du suivi d'événements pour Windows.

IF EXISTS(SELECT * FROM sys.server_event_sessions WHERE name='test_session')
    DROP EVENT session test_session ON SERVER;
GO
CREATE EVENT SESSION test_session
ON SERVER
    ADD EVENT sqlos.async_io_requested,
    ADD EVENT sqlserver.lock_acquired
    ADD TARGET package0.etw_classic_sync_target
        (SET default_etw_session_logfile_path = N'C:\demo\traces\sqletw.etl' )
    WITH (MAX_MEMORY=4MB, MAX_EVENT_SIZE=4MB);
GO

Exemple Azure SQL

Dans Azure SQL Managed Instance ou Azure SQL Database, stockez les fichiers .xel dans Stockage Blob Azure. Vous pouvez utiliser sys.fn_xe_file_target_read_file pour lire à partir de sessions d’événements étendues que vous créez vous-même et stockez dans Stockage Blob Azure. Par exemple, passez en revue le code cible du fichier d’événements pour les événements étendus dans Azure SQL Database et Azure SQL Managed Instance.

Les exemples de code peuvent différer pour Azure SQL Database et SQL Managed Instance

Certains exemples de code Transact-SQL écrits pour SQL Server ont besoin de changements mineurs pour s’exécuter sur Azure. Une catégorie de ces exemples de code implique des affichages catalogue dont les préfixes de nom diffèrent selon le type de moteur de base de données :

• server_ -  : préfixe pour SQL Server et Azure SQL Managed Instance
• database_ -  : préfixe pour Azure SQL Database et SQL Managed Instance

Azure SQL Database prend en charge uniquement les sessions d’événement incluses dans l’étendue de la base de données. SQL Server Management Studio (SSMS) prend complètement en charge les sessions d’événement incluses dans l’étendue de la base de données pour Azure SQL Database : un nœud Événements étendus contenant des sessions incluses dans l’étendue de la base de données apparaît sous chaque base de données dans Explorateur d’objets.

Azure SQL Managed Instance prend en charge les sessions incluses dans l’étendue de la base de données et les sessions incluses dans l’étendue du serveur. SSMS prend complètement en charge les sessions incluses dans l’étendue du serveur pour SQL Managed Instance : un nœud Événements étendus contenant toutes les sessions incluses dans l’étendue du serveur apparaît sous le dossier Gestion de chaque instance gérée dans Explorateur d'objets.

À titre d’illustration, le tableau suivant liste et compare deux sous-ensembles d’affichages catalogue. Par souci de concision, les sous-ensembles sont limités aux noms de vues qui contiennent également la chaîne _event. Les sous-ensembles ont des préfixes de noms différents car ils prennent en charge des types de moteur de base de données différents.

Les deux listes du tableau précédent sont exactes à compter de mars 2022. Pour obtenir une liste à jour, exécutez l’instruction Transact-SQL SELECT suivante :

SELECT name
    FROM sys.all_objects
    WHERE
        (name LIKE 'database[_]%' OR
         name LIKE 'server[_]%' )
        AND name LIKE '%[_]event%'
        AND type = 'V'
        AND SCHEMA_NAME(schema_id) = 'sys'
    ORDER BY name;

Voir aussi

• sys.server_event_sessions (Transact-SQL)
• sys.dm_xe_objects (Transact-SQL)
• sys.dm_xe_object_columns (Transact-SQL)

Étapes suivantes

• ALTER EVENT SESSION (Transact-SQL)
• DROP EVENT SESSION (Transact-SQL)