Partager via

  • Article

ALTER EVENT SESSION (Transact-SQL)

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

Icône Lien de rubriqueConventions de syntaxe Transact-SQL

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 = <valeur> [ ,...n] }

Spécifie des attributs personnalisables pour l'événement. Les attributs personnalisables apparaissent dans la vue sys.dm_xe_object_columns en tant que 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 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 vérifiée (true), le traitement de l'événement par les actions et les cibles pour la session se poursuit. Si <predicate_expression> n'est pas vérifiée (false), l'événement est abandonné par la session avant d'être traité par les actions et les cibles pour la session. 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énements 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 = <valeur> [, ...n] }

Définit un paramètre cible. Les paramètres cibles apparaissent dans la vue sys.dm_xe_object_columns en tant que column_type « personnalisable » et object_name = target_name.

ImportantImportant
Si vous utilisez la cible de mémoire tampon en anneau, il est préférable de configurer le paramètre cible max_memory avec 2 048 kilo-octets (Ko) pour éviter les éventuelles données tronquées dans le résultat XML. Pour plus d'informations sur les différents types de cibles, 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 admis 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 seront 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.

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.

RemarqueRemarque
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 doit être défini uniquement pour autoriser les événements uniques supérieurs à MAX_MEMORY. Si vous lui affectez une valeur inférieure à MAX_MEMORY, une erreur est générée. size est un nombre entier et peut s'exprimer en kilo-octets (KB) ou en mégaoctets (MB). 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 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_NODEUn jeu de mémoires tampons est créé pour chaque nœud NUMA. Pour plus d'informations, consultez Présentation de l'accès NUMA (Non-uniform Memory Access).
PER_CPUUn jeu de mémoires tampons est créé pour chaque UC.

TRACK_CAUSALITY ={ ON | OFF }

Indique si la causalité fait l'objet d'un suivi. Si cette option est activée, la causalité permet à des événements associés sur différentes connexions au serveur d'être corrélés.

STARTUP_STATE ={ ON | OFF }

Indique si cette session d'événements doit être ouverte automatiquement au démarrage de SQL Server.

RemarqueRemarque
Si STARTUP_STATE = ON, la session d'événements n'est activée que si SQL Server est arrêté, puis redémarré.
TermeDéfinition
ONLa session d'événements est lancée au démarrage.
OFFLa session d'événements n'est pas lancée au démarrage.

Notes

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

Autorisations

Requiert l'autorisation CONTROL SERVER.

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

Historique des modifications

Mise à jour du contenu

Correction de la valeur par défaut pour l'argument MAX_DISPATCH_LATENCY.

Insertion d'une note Important dans la description de SET { target_parameter_name = <valeur> [, ...n] }.