CREATE EVENT SESSION (Transact-SQL)

Articolo
05/30/2024

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

Crea una sessione degli eventi estesi che identifica l'origine degli eventi, le destinazioni delle sessione degli eventi e le opzioni della sessione degli eventi.

Convenzioni relative alla sintassi Transact-SQL

Sintassi

CREATE EVENT SESSION event_session_name
ON { SERVER | DATABASE }
{  
    <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 è 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] }

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 è 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'evento viene eliminato, evitando azioni aggiuntive e l'elaborazione di destinazione. Le espressioni di predicato sono limitate a 3.000 caratteri.

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

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 Unicode come richiesto dal paragone del predicato. Non viene eseguita alcuna conversione del tipo di stringa implicita per le funzioni del paragone del predicato. Il passaggio del tipo non corretto comporta un errore.

ADD TARGET [event_module_guid].event_package_name.target_name

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

Per visualizzare tutti i parametri di destinazione e le relative descrizioni, eseguire la query seguente, sostituendo il target-name segnaposto con il nome di destinazione, ad esempio event_file, ring_buffer, histograme così via.

SELECT name AS target_parameter_name,
       column_value AS default_value,
       description
FROM sys.dm_xe_object_columns
WHERE column_type = 'customizable'
      AND
      object_name = 'target-name';

Importante

Se si usa la destinazione del buffer circolare, è consigliabile impostare il MAX_MEMORY parametro di destinazione (distinto dal parametro di MAX_MEMORY sessione) su 1024 kilobyte (KB) o meno per evitare possibili troncamenti dei dati dell'output XML.

Per altre informazioni sui tipi di destinazione, vedere Destinazioni per gli eventi estesi in 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 megabyte (MB). La quantità massima non può superare 2 GB (minore di 2.048 MB). Tuttavia, l'uso di valori di memoria nell'intervallo GB non è consigliato.

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 degli eventi 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. L'uso di NO_EVENT_LOSS può causare problemi di prestazioni rilevabili mentre la sessione eventi è attiva. Le connessioni utente potrebbero bloccarsi in attesa che gli eventi vengano scaricati dal buffer.

Nota

Per le destinazioni dei file di eventi in database SQL di Azure e in Istanza gestita di SQL di Azure con i criteri di aggiornamento sempre aggiornati, a partire da giugno 2024, NO_EVENT_LOSS si comporta come ALLOW_SINGLE_EVENT_LOSS. Se si specifica NO_EVENT_LOSS, un avviso con ID messaggio 25665, gravità 10 e messaggio Questa destinazione non supporta la modalità di conservazione degli eventi NO_EVENT_LOSS. Viene invece usata la modalità di conservazione ALLOW_SINGLE_EVENT_LOSS. viene restituito e viene creata la sessione.

Questa modifica evita timeout di connessione, ritardi di failover e altri problemi che possono ridurre la disponibilità del database quando NO_EVENT_LOSS viene usato con le destinazioni dei file di eventi nell'archiviazione BLOB di Azure.

NO_EVENT_LOSS verrà rimosso come argomento di EVENT_RETENTION_MODE supportato negli aggiornamenti futuri di database SQL di Azure e Istanza gestita di SQL di Azure. Evitare di usare questa funzionalità in un nuovo progetto di sviluppo e prevedere interventi di modifica nelle applicazioni in cui è attualmente implementata.

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. 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 nelle 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 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 MAX_EVENT_SIZE è impostato, vengono creati due buffer di dimensioni oltre a MAX_MEMORY e la memoria totale usata per il buffer degli eventi è 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.

Nota

Se STARTUP_STATE = ON, la sessione dell'evento verrà avviata solo se SQL Server viene arrestato e quindi riavviato.

ON La sessione eventi ha inizio all'avvio.

OFF La sessione eventi non viene avviata 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

In SQL Server e Istanza gestita di SQL è richiesta l'autorizzazione CREATE ANY EVENT SESSION (introdotta in SQL Server 2022) o ALTER ANY EVENT SESSION .

Nel database SQL è richiesta l'autorizzazione ALTER ANY DATABASE EVENT SESSION nel database.

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

Esempio di SQL Server

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

Esempio per Azure SQL

In Istanza gestita di SQL di Azure o nel database SQL di Azure archiviare i file con estensione xel in Archiviazione BLOB di Azure. È possibile usare sys.fn_xe_file_target_read_file per eseguire la lettura da sessioni eventi estese create manualmente e archiviarle in Archiviazione BLOB di Azure. Per una procedura dettagliata di esempio, esaminare Codice di destinazione del file eventi per gli eventi estesi nel database SQL di Azure e in Istanza gestita di SQL di Azure.

Gli esempi di codice per il database SQL di Azure e Istanza gestita di SQL possono essere diversi

Alcuni esempi di codice Transact-SQL scritti per SQL Server richiedono qualche piccola modifica per funzionare in Azure. Una categoria di tali esempi di codice prevede viste del catalogo i cui prefissi del nome differiscono a seconda del tipo di motore di database:

server_ - prefisso per SQL Server e Istanza gestita di SQL di Azure
database_ - prefisso per il database SQL di Azure e Istanza gestita di SQL

Database SQL di Azure supporta solo sessioni di eventi con ambito database. SQL Server Management Studio (SSMS) supporta completamente le sessioni di eventi con ambito database per il database SQL di Azure: un nodo Eventi estesi contenente sessioni con ambito database viene visualizzato in ogni database in Esplora oggetti.

Istanza gestita di SQL di Azure supporta sia sessioni con ambito database che sessioni con ambito server. SSMS supporta completamente le sessioni con ambito server per Istanza gestita di SQL: un nodo Eventi estesi contenente tutte le sessioni con ambito server viene visualizzato nella cartella Gestione per ogni istanza gestita in Esplora oggetti.

Nota

Le sessioni con ambito server sono consigliate per le istanze gestite. Le sessioni con ambito database non vengono visualizzate in Esplora oggetti in SSMS per Istanza gestita di SQL di Azure. Le sessioni con ambito database possono essere sottoposte a query e gestite solo con Transact-SQL quando si usa un'istanza gestita.

Come riferimento visivo, la tabella seguente elenca e confronta due subset delle viste di catalogo. Per brevità, i subset sono limitati ai nomi di vista che contengono anche la stringa _event. I subset hanno prefissi di nome diversi perché supportano diversi tipi di motori di database.

Nome in SQL Server e Istanza gestita di SQL di Azure	Nome nel database SQL di Azure e Istanza gestita di SQL di Azure
server_event_notifications server_event_session_actions server_event_session_events server_event_session_fields server_event_session_targets server_event_sessions server_events server_trigger_events	database_event_session_actions database_event_session_events database_event_session_fields database_event_session_targets database_event_sessions

I due elenchi nella tabella precedente sono stati aggiornati al mese di marzo 2022. Per un elenco aggiornato, eseguire l'istruzione SELECT Transact-SQL seguente:

SELECT name
    FROM sys.all_objects
    WHERE
        (name LIKE 'database[_]%' OR
         name LIKE 'server[_]%' )
        AND name LIKE '%[_]event%'
        AND type = 'V'
        AND SCHEMA_NAME(schema_id) = 'sys'
    ORDER BY name;

Condividi tramite

CREATE EVENT SESSION (Transact-SQL)

Sintassi

Argomenti

event_session_name

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>

ADD TARGET [event_module_guid].event_package_name.target_name

SET { target_parameter_name= <value> [, ...n] }

WITH ( <event_session_options> [ ,...n] )

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 }

Osservazioni:

Autorizzazioni

Esempi

Esempio di SQL Server

Esempio per Azure SQL

Gli esempi di codice per il database SQL di Azure e Istanza gestita di SQL possono essere diversi

Vedi anche

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive