ALTER EVENT SESSION (Transact-SQL)

s’applique à :SQL ServerAzure SQL Managed Instance

Démarre ou arrête une session d'événements, ou modifie la configuration d'une session d'événements.

Conventions de la syntaxe Transact-SQL

Syntaxe

ALTER EVENT SESSION event_session_name
ON { SERVER | DATABASE }
{
    [ [ {  <add_drop_event> [ , ...n ] }
       | { <add_drop_event_target> [ , ...n ] } ]
    [ WITH ( <event_session_options> [ , ...n ] ) ]
    ]
    | [ STATE = { START | STOP } ]
}

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

<event_specifier> ::=
{
[event_module_guid].event_package_name.event_name
}
<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'
}

<add_drop_event_target>::=
{
    ADD TARGET <event_target_specifier>
        [ ( SET { target_parameter_name = <value> [ , ...n ] } ) ]
    | DROP TARGET <event_target_specifier>
}

<event_target_specifier>::=
{
    [event_module_guid].event_package_name.target_name
}

<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 } ]
    [ [ , ] MAX_DURATION = { <time duration> { SECONDS | MINUTES | HOURS | DAYS } | UNLIMITED } ]
}

Arguments

event_session_name

Nom d’une session d’événements existante.

STATE = START | ARRÊTER

Démarre ou arrête la session d'événements. L’argument STATE doit être spécifié seul. Elle ne peut pas être combinée avec d’autres arguments dans la même ALTER EVENT SESSION instruction.

AJOUTER ÉVÉNEMENT <event_specifier>

Identifie un événement à associer à la session d’événements. < > event_specifier se présente sous la forme de [event_module_guid].event_package_name. event_name, où :

• event_module_guid est le GUID du module qui contient l’événement.
• event_package_name est le package qui contient l’événement.
• event_name est le nom de l’événement.

Vous trouverez des événements disponibles en exécutant la requête suivante :

SELECT o.name AS event_name,
       o.description AS event_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'event'
ORDER BY event_name ASC;

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

Attributs personnalisables pour l’événement.

Vous trouverez des attributs personnalisables pour un événement donné en exécutant la requête suivante :

SELECT object_name,
       name AS column_name,
       type_name,
       column_value,
       description
FROM sys.dm_xe_object_columns
WHERE object_name = 'event-name-placeholder'
      AND column_type = 'customizable'
ORDER BY column_name ASC;

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

Action à associer à l’événement, où :

• event_module_guid est le GUID du module qui contient l’action.
• event_package_name est le package qui contient l’action.
• action_name est le nom de l’action.

Vous trouverez des actions disponibles en exécutant la requête suivante :

SELECT o.name AS action_name,
       o.description AS action_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'action'
ORDER BY action_name ASC;

OÙ <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. Chaque expression de prédicat est limitée à 3 000 caractères.

event_field_name

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

Vous trouverez les champs d’un événement en exécutant la requête suivante :

SELECT oc.name AS field_name,
       oc.type_name AS field_type,
       oc.description AS field_description
FROM sys.dm_xe_objects AS o
INNER JOIN sys.dm_xe_packages AS p
ON o.package_guid = p.guid
INNER JOIN sys.dm_xe_object_columns AS oc
ON o.name = oc.object_name
   AND
   o.package_guid = oc.object_package_guid
WHERE o.object_type = 'event'
      AND
      o.name = 'event-name-placeholder'
      AND
      oc.column_type = 'data'
ORDER BY field_name ASC;

[event_module_guid]. event_package_name. predicate_source_name

Nom de la source de prédicat global où :

• event_module_guid est le GUID du module qui contient l’événement.
• event_package_name est le package qui contient l’objet source de prédicat.
• predicate_source_name est le nom de la source de prédicat.

Les sources de prédicat sont disponibles en exécutant la requête suivante :

SELECT o.name AS predicate_source_name,
       o.description AS predicate_source_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'pred_source'
ORDER BY predicate_source ASC;

[event_module_guid].event_package_name.predicate_compare_name

Nom de l’objet comparateur de prédicat, où :

• event_module_guid est le GUID du module qui contient l’événement.
• event_package_name est le package qui contient l’objet comparateur de prédicat.
• predicate_compare_name est le nom du comparateur de prédicat.

Vous trouverez des comparateurs de prédicats en exécutant la requête suivante :

SELECT o.name AS predicate_comparator_name,
       o.description AS predicate_comparator_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'pred_compare'
ORDER BY predicate_comparator ASC;

number

Tout type numérique pouvant être représenté sous la forme d’un entier 64 bits.

'string'

Chaîne ANSI ou Unicode requise par le comparateur de prédicat. Aucune conversion implicite de type chaîne n'est effectuée pour les fonctions de comparaison de prédicat. Le passage de la valeur d’un type inattendu entraîne une erreur.

ÉVÉNEMENT <DE CHUTE event_specifier>

Identifie un événement à supprimer de la session d’événements. Le spécificateur d’événement se présente sous la forme [event_module_guid]. event_package_name. event_name, 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.

  < > event_specifier devez identifier un événement qui a été précédemment ajouté à la session d’événements.

AJOUTER CIBLE <event_target_specifier>

Identifie une cible à associer à une session d’événements. Le spécificateur cible d’événement se présente sous la forme [event_module_guid]. event_package_name. target_name, 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 le nom de la cible.

Vous trouverez des cibles disponibles en exécutant la requête suivante :

SELECT o.name AS target_name,
       o.description AS target_description,
       o.capabilities_desc,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'target'
ORDER BY target_name ASC;

Une session d’événements peut avoir zéro, un ou plusieurs cibles. Toutes les cibles ajoutées à une session d’événements doivent être différentes. Par exemple, vous ne pouvez pas ajouter une deuxième event_file cible à une session qui a déjà une event_file cible.

Pour plus d’informations, notamment des exemples d’utilisation pour les cibles couramment utilisées, consultez les cibles d’événements étendus.

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 target-name-placeholder par le nom cible, tel que event_file, ring_buffer, histogram, etc.

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-placeholder';

Important

Si vous utilisez la cible de mémoire tampon en anneau, nous vous recommandons de définir le MAX_MEMORY paramètre cible (distinct du MAX_MEMORY paramètre de session) sur 1 024 kilo-octets (Ko) ou moins pour éviter la troncation de données possible de la sortie XML.

Pour plus d’informations sur les types de cibles, consultez les cibles d’événements étendus.

LARGUER <event_target_specifier>

Identifie une cible à supprimer d’une session d’événements. Le spécificateur cible d’événement se présente sous la forme [event_module_guid]. event_package_name. target_name, 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 le nom de la cible.

Le spécificateur de cible d’événement doit identifier une cible qui a été précédemment ajoutée à la session d’événements.

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

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

MAX_MEMORY = taille [ Ko | Mo ]

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 (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 complètes réduit l’impact sur les performances tout en réduisant également la perte de données dans le 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 évite généralement l’impact sur les performances sur le serveur lorsque les mémoires tampons d’événements sont rapidement remplies, mais un grand nombre d’événements peuvent être perdus à partir 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 sessions et requêtes utilisateur peuvent se bloquer en attendant que les événements soient vidés à partir de la mémoire tampon.

  Note

  Pour les cibles de fichier d’événements dans Azure SQL Database et dans Azure SQL Managed Instance (avec la stratégie de mise à jour sql Server 2025 ou Always-up-to-date), à partir de juin 2024, NO_EVENT_LOSS se comporte de la même façon que ALLOW_SINGLE_EVENT_LOSS. Si vous spécifiez NO_EVENT_LOSS, un avertissement avec l’ID de message 25665, la gravité 10 et le message This target doesn't support the NO_EVENT_LOSS event retention mode. The ALLOW_SINGLE_EVENT_LOSS retention mode is used instead. est retourné, et la session est créée.

  Cette modification évite les délais d’expiration de connexion, les retards de basculement et d’autres problèmes qui peuvent réduire la disponibilité de la base de données lorsqu’elles NO_EVENT_LOSS sont utilisées avec des cibles de fichiers d’événements dans le stockage Blob Azure.

  NO_EVENT_LOSS est prévu pour la suppression en tant qu’argument pris en charge EVENT_RETENTION_MODE dans les futures mises à jour d’Azure SQL Database et d’Azure SQL Managed Instance. Évitez d'utiliser cette fonctionnalité dans de nouveaux travaux de développement, et prévoyez de modifier les applications qui utilisent actuellement cette fonctionnalité.

MAX_DISPATCH_LATENCY = { secondes SECONDES | 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.

• Secondes SECONDES

  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.

• INFINI

  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 = taille [ Ko | Mo ]

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 = { AUCUN | PER_NODE | PER_CPU }

Spécifie l’affinité des mémoires tampons d’événements. Les options autres que NONE les mémoires tampons et la consommation de mémoire supérieure peuvent éviter la contention et améliorer les performances sur les ordinateurs plus volumineux.

• Aucune

  Un ensemble unique de mémoires tampons est créé dans l’instance du moteur de base de données.

• PER_NODE

  Un ensemble de mémoires tampons est créé pour chaque nœud NUMA.

• PER_CPU

  Un ensemble de mémoires tampons est créé pour chaque uc.

TRACK_CAUSALITY = { ON | OFF }

Spécifie si la causalité de l’événement 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 s’il faut démarrer ou non automatiquement cette session d’événements au démarrage du moteur de base de données.

Note

Si STARTUP_STATE = ON, la session d’événements démarre lorsque le moteur de base de données est arrêté, puis redémarré. Pour démarrer immédiatement la session d’événements, utilisez ALTER EVENT SESSION ... ON SERVER STATE = START.

• ACTIVÉ

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

• OFF

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

MAX_DURATION = { durée { durée { SECONDES | MINUTES | HEURES | DAYS } | ILLIMITÉ }

S’applique à : SQL Server 2025 (17.x)

• ILLIMITÉ

  Provoque l’exécution d’une session d’événements indéfiniment une fois démarrée, jusqu’à ce qu’elle soit arrêtée à l’aide de l’instruction ALTER EVENT SESSION ... STATE = STOP .

• durée SECONDS | MINUTES | HEURES | JOURS

  Provoque l’arrêt automatique d’une session d’événements après le délai spécifié après le démarrage de la session. La durée maximale prise en charge est de 2 147 483 secondes, soit 35 792 minutes, soit 596 heures ou 24 jours.

Pour plus d’informations, consultez sessions d’événements liées au temps.

Notes

Pour plus d’informations sur les arguments de session d’événements, consultez sessions Événements étendus.

Les ADD arguments et DROP les arguments ne peuvent pas être utilisés dans la même instruction.

autorisations

SQL Server et Azure SQL Managed Instance nécessitent l’autorisation ALTER ANY EVENT SESSION .

Azure SQL Database nécessite l’autorisation ALTER ANY DATABASE EVENT SESSION dans la base de données.

Conseil

SQL Server 2022 a introduit des autorisations plus granulaires pour les événements étendus. Pour plus d’informations, consultez Blog : Nouvelles autorisations granulaires pour SQL Server 2022 et Azure SQL afin d’améliorer l’adhésion à PoLP.

Exemples

A. Démarrer et arrêter une session d’événements

Pour utiliser cet exemple avec des sessions d’événements de base de données, remplacez ON SERVER par ON DATABASE.

ALTER EVENT SESSION test_session ON SERVER STATE = START;
ALTER EVENT SESSION test_session ON SERVER STATE = STOP;

B. Ajouter de nouveaux événements à une session existante

Pour utiliser cet exemple avec des sessions d’événements de base de données, remplacez ON SERVER par ON DATABASE.

ALTER EVENT SESSION test_session ON SERVER
ADD EVENT sqlserver.database_transaction_begin,
ADD EVENT sqlserver.database_transaction_end;

Chapitre C. Afficher les statistiques de session

Pour utiliser cet exemple avec des sessions d’événements de base de données, remplacez sys.dm_xe_sessions par sys.dm_xe_database_sessions, et sys.dm_xe_session_events par sys.dm_xe_database_session_events.

SELECT *
FROM sys.dm_xe_sessions
WHERE name = 'test_session';

SELECT se.*
FROM sys.dm_xe_session_events AS se
WHERE EXISTS (SELECT 1
              FROM sys.dm_xe_sessions AS s
              WHERE s.address = se.event_session_address
                    AND s.name = 'test_session');

Contenu connexe

• CRÉER SESSION D'ÉVÉNEMENT (Transact-SQL)
• SESSION D’ÉVÉNEMENT DE SUPPRESSION (Transact-SQL)
• Cibles des Événements étendus SQL Server
• sys.server_event_sessions (Transact-SQL)
• sys.dm_xe_objects (Transact-SQL)
• sys.dm_xe_object_columns (Transact-SQL)