CREATE EVENT SESSION (Transact-SQL)

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 syntaxe Transact-SQL.

Syntaxe

CREATE EVENT SESSION event_session_name
ON SERVER
{
    <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 des 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 = <valeur> [ ,...n] }
  Autorise les attributs personnalisables pour l'événement à définir. 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 ».

• number
  Tout type numérique, y compris 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.

  • Le target_name est la cible. Les cibles apparaissent dans la vue sys.dm_xe_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.

  Important

  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.

• WITH ( <event_session_options> [ ,...n] ) )
  Spécifie les options à utiliser avec la session d'événements.

• MAX_MEMORY = size [ 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. size est un nombre entier et peut s'exprimer en kilo-octets (Ko) ou en mégaoctets (Mo).

• 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 de la session 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 seront 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.

    [!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 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_NODE
    Un 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_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.

  [!REMARQUE]

  Si STARTUP_STATE = ON, la session d'événements se lance 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

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

Autorisations

Requiert l'autorisation CONTROL SERVER.

Exemples

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

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] }.

Voir aussi

Référence

ALTER EVENT SESSION (Transact-SQL)

DROP EVENT SESSION (Transact-SQL)

sys.server_event_sessions (Transact-SQL)

sys.dm_xe_objects (Transact-SQL)

sys.dm_xe_object_columns (Transact-SQL)