ALTER EVENT SESSION (Transact-SQL)

Article
05/30/2024

S’applique à : SQL Server Azure SQL Managed Instance

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

Syntaxe

ALTER EVENT SESSION event_session_name  
ON SERVER  
{  
    [ [ {  <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 } ]  
}

Arguments

Terme	Définition
event_session_name	Nom d'une session d'événements existante.
STATE = START \| STOP	Démarre ou arrête la session d'événements. Cet argument est valide uniquement lorsque ALTER EVENT SESSION est appliqué à un objet de la session d'événements.
ADD EVENT <event_specifier>	Associe l’événement identifié par <event_specifier> à la session d’événements.
[event_module_guid] .event_package_name.event_name	Nom d'un événement d'un package d'é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 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] }	Spécifie des attributs personnalisables pour l'événement. Les attributs personnalisables s’affichent dans la vue sys.dm_xe_object_columns sous la forme column_type 'customizable' 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 actions 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’action et le traitement cible ne se produisent pas pour cet événement. Les expressions de prédicat sont limitées à 3 000 caractères, ce qui limite les arguments de chaîne.
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 qu’object_type « pred_source ».
[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 qu’object_type « pred_compare ».
DROP EVENT <event_specifier>	Supprime l’événement identifié par <event_specifier>. <event_specifier> doit être valide dans la session d’événements.
ADD TARGET <event_target_specifier>	Associe la cible identifiée par <event_target_specifier> à la session d’événements.
[event_module_guid].event_package_name.target_name	Nom d'une cible de 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 l’action. Les actions apparaissent dans la vue sys.dm_xe_objects en tant qu'object_type « cible ».
SET { target_parameter_name= <value> [, ...n] }	Définit un paramètre cible. Les paramètres cibles apparaissent dans la vue sys.dm_xe_object_columns sous la forme column_type 'customizable' et object_name = target_name. Remarque : si vous utilisez la cible de mémoire tampon en anneau, nous vous recommandons de définir le paramètre cible max_memory sur 2 048 kilo-octets (Ko) pour éviter la troncation possible des données de la sortie XML. Pour plus d’informations sur le moment où les différents types de cibles doivent être utilisés, consultez Cibles des événements étendus SQL Server.
DROP TARGET <event_target_specifier>	Supprime la cible identifiée par <event_target_specifier>. <event_target_specifier> doit être valide dans la session d’événements.
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. Cela peut entraîner des problèmes de performance 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. Pour les cibles de fichier d’événements dans Azure SQL Database, se comporte comme ALLOW_SINGLE_EVENT_LOSS. Pour plus d’informations, consultez EVENT_RETENTION_MODE.
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. La valeur de latence minimale est 1 seconde. Toutefois, la valeur 0 peut être utilisée pour spécifier une latence INFINITE. 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. 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. Remarque : MAX_DISPATCH_LATENCY = 0 SECONDS est équivalent à MAX_DISPATCH_LATENCY = INFINITE.
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. Quand MAX_EVENT_SIZE est défini, deux mémoires tampons de size sont créées en plus de MAX_MEMORY. Cela signifie que 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 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. Si STARTUP_STATE=ON, la session d’événements démarre uniquement si SQL Server est arrêté, puis redémarré. ON= La session d’événements est lancée au démarrage. OFF = La session d’événements n’est PAS lancée au démarrage.

Notes

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

autorisations

Nécessite l’autorisation ALTER ANY EVENT SESSION.

Conseil

SQL Server 2022 a introduit un certain nombre d’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

L'exemple suivant démarre une session d'événements, récupère quelques statistiques de session en temps réel, puis ajoute deux événements à la session existante.

-- Start the event session  
ALTER EVENT SESSION test_session ON SERVER  
STATE = start;  
GO  

-- Obtain live session statistics   
SELECT * FROM sys.dm_xe_sessions;  
SELECT * FROM sys.dm_xe_session_events;  
GO  
  
-- Add new events to the session  
ALTER EVENT SESSION test_session ON SERVER  
ADD EVENT sqlserver.database_transaction_begin,  
ADD EVENT sqlserver.database_transaction_end;  
GO

Partager via

ALTER EVENT SESSION (Transact-SQL)

Syntaxe

Arguments

Notes

autorisations

Exemples

Voir aussi

Commentaires

Ressources supplémentaires