CREATE EVENT SESSION (Transact-SQL)

Sintassi

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

Argomenti

• event_session_name
  Nome definito dall'utente per la sessione eventi. event_session_name è un valore alfanumerico, può essere composto da un massimo di 128 caratteri, deve essere univoco all'interno di un'istanza di SQL Server e deve essere conforme alle regole relative agli identificatori.

• ADD EVENT [ event_module_guid ].event_package_name.event_name
  Evento da associare alla sessione dell'evento, dove:

  • event_module_guid è il GUID del modulo contenente l'evento.

  • event_package_name è il pacchetto che contiene l'oggetto dell'azione.

  • event_name è l'oggetto dell'evento.

  Gli eventi vengono visualizzati nella vista sys.dm_xe_objects come object_type "event".

• SET { event_customizable_attribute = <value> [ ,...n] }
  Consente gli attributi personalizzabili per l'evento da impostare. Gli attributi personalizzabili vengono visualizzati nella vista sys.dm_xe_object_columns come column_type 'customizable' e object_name = event_name.

• ACTION ( { [event_module_guid].event_package_name.action_name [ ,...n] })
  Azione da associare alla sessione dell'evento, dove:

  • event_module_guid è il GUID del modulo contenente l'evento.

  • event_package_name è il pacchetto che contiene l'oggetto dell'azione.

  • action_name è l'oggetto dell'azione.

  Le azioni vengono visualizzate nella vista sys.dm_xe_objects come object_type "action".

• WHERE <predicate_expression>
  Indica l'espressione del predicato utilizzata per determinare se un evento deve essere elaborato. Se <predicate_expression> è True, l'evento viene elaborato ulteriormente dalle azioni e dalle destinazioni della sessione. Se <predicate_expression> è False, l'evento viene eliminato dalla sessione prima di essere elaborato dalle azioni e dalle destinazioni della sessione. Le espressioni del predicato possono essere composte da massimo 3000 caratteri, che costituisce un limite per gli argomenti di tipo stringa.

• event_field_name
  Nome del campo relativo all'evento che identifica l'origine del predicato.

• [event_module_guid].event_package_name.predicate_source_name
  Nome dell'origine del predicato globale dove:

  • event_module_guid è il GUID del modulo contenente l'evento.

  • event_package_name è il pacchetto che contiene l'oggetto del predicato.

  • predicate_source_name è definito nella vista sys.dm_xe_objects come object_type "pred_source".

• [event_module_guid].event_package_name.predicate_compare_name
  Nome dell'oggetto del predicato da associare all'evento, dove:

  • event_module_guid è il GUID del modulo contenente l'evento.

  • event_package_name è il pacchetto che contiene l'oggetto del predicato.

  • predicate_compare_name è un'origine globale definita nella vista sys.dm_xe_objects come object_type "pred_compare".

• number
  Qualsiasi tipo numerico incluso decimal. Le limitazioni sono la mancanza di memoria fisica disponibile o un numero troppo grande per essere rappresentato come un numero intero a 64 bit.

• 'string'
  Stringa ANSI o una stringa Unicode come richiesto dal paragone del predicato. Non viene eseguita alcuna conversione del tipo di stringa implicita per le funzioni di confronto del predicato. Se viene passato il tipo errato, viene generato un errore.

• ADD TARGET [event_module_guid].event_package_name.target_name
  Destinazione da associare alla sessione dell'evento, dove:

  • event_module_guid è il GUID del modulo contenente l'evento.

  • event_package_name è il pacchetto che contiene l'oggetto dell'azione.

  • target_name è la destinazione. Le destinazioni vengono visualizzate nella vista sys.dm_xe_objects come object_type 'target'.

• SET { target_parameter_name = <value> [, ...n] }
  Imposta un parametro di destinazione. I parametri di destinazione vengono visualizzati nella vista sys.dm_xe_object_columns come column_type 'customizable' e object_name = target_name.

  Importante
  Se si utilizza la destinazione buffer circolare, si consiglia di impostare il parametro di destinazione max_memory su 2048 kilobyte (KB) per evitare il possibile troncamento dei dati dell'output XML. Per ulteriori informazioni sui casi in cui è possibile utilizzare i diversi tipi di destinazione, vedere Destinazioni degli eventi estesi di SQL Server.

• WITH ( <event_session_options> [ ,...n] )
  Specifica le opzioni da utilizzare con la sessione eventi.

• MAX_MEMORY = size [ KB | MB ]
  La quantità di memoria allocata alla sessione per la memorizzazione degli eventi nel buffer. Il valore predefinito è 4 MB. size è un numero intero e può essere espresso in kilobyte (KB) o in megabyte (MB).

• EVENT_RETENTION_MODE = { ALLOW_SINGLE_EVENT_LOSS | ALLOW_MULTIPLE_EVENT_LOSS | NO_EVENT_LOSS }
  Specifica la modalità di memorizzazione dell'evento da utilizzare per la gestione della perdita di eventi.

  • ALLOW_SINGLE_EVENT_LOSS
    Un evento può essere perso dalla sessione. Un evento singolo viene eliminato solo quando tutti i buffer dell'evento sono pieni. La perdita di un singolo evento i buffer sono pieni garantisce un livello accettabile delle prestazioni di SQL Server, riducendo al minimo il rischio di perdita dei dati nel flusso di eventi elaborati.

  • ALLOW_MULTIPLE_EVENT_LOSS
    È possibile che vengano persi i buffer dell'evento pieni contenenti più eventi. Il numero di eventi persi dipende dalla dimensione della memoria allocata alla sessione, dalla partizione della memoria e dalla dimensione degli eventi nel buffer. Questa opzione riduce al minimo l'impatto sulle prestazioni dei server quando i buffer degli eventi vengono riempiti rapidamente, ma numerosi eventi della sessione possono andare persi.

  • NO_EVENT_LOSS
    Non è consentita alcuna perdita di eventi. Questa opzione assicura che tutti gli eventi generati vengano mantenuti. L'utilizzo di questa opzione forza tutte le attività che attivano eventi ad aspettare fino a che lo spazio è disponibile in un buffer degli eventi. Questo può condurre a problemi di prestazione mentre la sessione dell'evento è attiva. Le connessioni utente potrebbero bloccarsi in attesa che gli eventi vengano scaricati dal buffer.

• MAX_DISPATCH_LATENCY = { seconds SECONDS | INFINITE }
  Specifica il tempo necessario all'esecuzione del buffer degli eventi nella memoria prima che vengano resi disponibili nelle destinazioni della sessione eventi. Per impostazione predefinita, questo valore è impostato su 30 secondi.

  • seconds SECONDS
    Tempo di attesa, espresso in secondi, prima che venga avviato lo scaricamento dei buffer alle destinazioni. seconds è un numero intero. Il valore di latenza minimo è 1 secondo. È tuttavia possibile utilizzare il valore 0 per specificare una latenza infinita.

  • INFINITE
    Scarica i buffer nelle destinazioni solo quando i buffer sono pieni o alla chiusura della sessione eventi.

    [!NOTA]

    MAX_DISPATCH_LATENCY = 0 SECONDS è equivalente a MAX_DISPATCH_LATENCY = INFINITE.

• MAX_EVENT_SIZE = size [ KB | MB ]
  Specifica la dimensione massima consentita per gli eventi. Il valore di MAX_EVENT_SIZE deve essere impostato solo per consentire singoli eventi di dimensioni superiori a quelle indicate da MAX_MEMORY. Se viene impostato un valore inferiore a quello di MAX_MEMORY, viene generato un errore. size è un numero intero e può essere espresso in kilobyte (KB) o in megabyte (MB). Se size viene indicato in kilobyte, la dimensione minima consentita è di 64 KB. Quando viene impostato MAX_EVENT_SIZE, vengono creati due buffer con dimensioni pari a size in aggiunta a MAX_MEMORY. Ciò significa che la memoria totale utilizzata per la memorizzazione degli eventi nel buffer è MAX_MEMORY + 2 * MAX_EVENT_SIZE.

• MEMORY_PARTITION_MODE = { NONE | PER_NODE | PER_CPU }
  Specifica la posizione di creazione dei buffer degli eventi.

  • NONE
    Nell'istanza di SQL Server viene creato un unico set di buffer.

  • PER_NODE
    Viene creato un set di buffer per ogni nodo NUMA. Per ulteriori informazioni, vedere Informazioni sull'architettura NUMA (Non-Uniform Memory Access).

  • PER_CPU
    Viene creato un set di buffer per ogni CPU.

• TRACK_CAUSALITY = { ON | OFF }
  Specifica se viene tenuta traccia della causalità. Se attivato, la causalità consente la correlazione di eventi correlati in diverse connessioni server.

• STARTUP_STATE = { ON | OFF }
  Specifica se avviare automaticamente questa sessione dell'evento all'avvio di SQL Server.

  [!NOTA]

  Se STARTUP_STATE = ON, la sessione dell'evento viene avviata solo se SQL Server viene interrotto e successivamente riavviato.

  • ON
    La sessione dell'evento ha inizio all'avvio.

  • OFF
    La sessione dell'evento non ha inizio all'avvio.

Osservazioni

L'ordine di precedenza degli operatori logici prevede NOT come operatore con precedenza massima, seguito da AND e quindi da OR.

Autorizzazioni

È richiesta l'autorizzazione CONTROL SERVER.

Esempi

Nell'esempio seguente viene illustrato come creare una sessione dell'evento denominata test_session. In questo esempio vengono aggiunti due eventi e viene utilizzata la destinazione Analisi eventi per 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

Cronologia modifiche

Vedere anche

Riferimento