ALTER EVENT SESSION (Transact-SQL)

Si applica a: SQL Server Istanza gestita di SQL di Azure

Consente di avviare o arrestare una sessione eventi oppure di modificare la configurazione di una sessione eventi.

Convenzioni relative alla sintassi Transact-SQL

Sintassi

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

Argomenti

Termine	Definizione
event_session_name	Nome di una sessione dell'evento esistente.
STATE = START | FERMARSI	Avvia o arresta la sessione dell'evento. Questo argomento è valido solo quando ALTER EVENT SESSION è applicato a un oggetto della sessione dell'evento.
ADD EVENT <event_specifier>	Associa l'evento identificato da <event_specifier> con la sessione dell'evento.
[event_module_guid].event_package_name.event_name	Nome di un evento in un pacchetto dell'evento dove: - event_module_guid è l'identificatore univoco globale (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] }	Specifica gli attributi personalizzabili per l'evento. 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 è l'identificatore univoco globale (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'elaborazione dell'azione e della destinazione non si verifica per questo evento. Le espressioni di predicato sono limitate a 3.000 caratteri, che limitano gli argomenti stringa.
event_field_name	Nome del campo relativo all'evento che consente di identificare l'origine del predicato.
[event_module_guid].event_package_name.predicate_source_name	Nome dell'origine del predicato globale dove: - event_module_guid è l'identificatore univoco globale (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 è l'identificatore univoco globale (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'.
DROP EVENT <event_specifier>	Elimina l'evento identificato da <event_specifier>. <event_specifier> deve essere valido nella sessione dell'evento.
ADD TARGET <event_target_specifier>	Associa la destinazione identificata da <event_target_specifier> alla sessione dell'evento.
[event_module_guid].event_package_name.target_name	Nome di una destinazione nella sessione dell'evento dove: - event_module_guid è l'identificatore univoco globale (GUID) del modulo contenente l'evento. - event_package_name è il pacchetto che contiene l'oggetto dell'azione. - target_name è l'azione. Le azioni 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. Nota: se si usa la destinazione del buffer circolare, è consigliabile impostare il parametro di destinazione max_memory su 2.048 kilobyte (KB) per evitare possibili troncamenti dei dati dell'output XML. Per altre informazioni sull'uso dei diversi tipi di destinazione, vedere Destinazioni degli eventi estesi di SQL Server.
DROP TARGET <event_target_specifier>	Elimina la destinazione identificata da <event_target_specifier>. <event_target_specifier> deve essere valido nella sessione dell'evento.
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 siano 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. Per le destinazioni dei file di eventi in database SQL di Azure, si comporta come ALLOW_SINGLE_EVENT_LOSS. Per altre informazioni, vedere EVENT_RETENTION_MODE.
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. Il valore di latenza minimo è 1 secondo. È tuttavia possibile utilizzare il valore 0 per specificare una latenza infinita. 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. INFINITE Scarica i buffer nelle destinazioni solo quando i buffer sono pieni o alla chiusura della sessione dell'evento. 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. MAX_EVENT_SIZE deve essere impostato solo per consentire singoli eventi di dimensioni maggiori di MAX_MEMORY; impostandolo su meno di MAX_MEMORY genera un errore. size è un numero intero e può essere espresso in kilobyte (KB) o megabyte (MB). Se size è espresso 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 dell'evento. NONE All'interno dell'istanza di SQL Server viene creato un unico set di buffer. PER NODE: viene creato un set di buffer per ogni nodo NUMA. PER CPU: viene creato un set di buffer per ogni CPU.
TRACK_CAUSALITY = { ON | OFF }	Specifica se viene tenuta traccia della causalità. Se abilitato, la causalità consente la correlazione di eventi correlati in diverse connessioni server.
STARTUP_STATE = { ON | OFF }	Specifica se avviare automaticamente o meno questa sessione dell'evento all'avvio di SQL Server. Se STARTUP_STATE=ON la sessione eventi viene avviata solo se SQL Server viene arrestato e riavviato. ON= La sessione dell'evento ha inizio all'avvio. OFF = La sessione dell'evento non ha inizio all'avvio.

Osservazioni:

Gli ADD argomenti e DROP non possono essere usati nella stessa istruzione.

Autorizzazioni

È necessaria l'autorizzazione ALTER ANY EVENT SESSION.

Suggerimento

SQL Server 2022 ha introdotto una serie di nuove autorizzazioni più granulari per gli eventi estesi. Per altre informazioni, vedere Blog: Nuove autorizzazioni granulari per SQL Server 2022 e Azure SQL per migliorare la conformità con PoLP.

Esempi

Nell'esempio seguente viene avviata una sessione dell'evento, vengono ottenute alcune statistiche della sessione attiva e infine vengono aggiunti due eventi alla sessione esistente.

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

Vedi anche

• CREARE LA SESSIONE DI EVENTI (Transact-SQL)
• DROP EVENT SESSION (Transact-SQL)
• Destinazioni degli eventi estesi di SQL Server
• sys.server_event_sessions (Transact-SQL)
• sys.dm_xe_objects (Transact-SQL)
• sys.dm_xe_object_columns (Transact-SQL)