ALTER EVENT SESSION (Transact-SQL)

Artikel
05/30/2024

Gilt für: SQL Server Azure SQL Managed Instance

Startet oder beendet eine Ereignissitzung oder ändert die Konfiguration einer Ereignissitzung.

Syntax

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

Argumente

Begriff	Definition
event_session_name	Ist der Name einer vorhandenen Ereignissitzung.
STATE = START \| STOP	Startet oder beendet die Ereignissitzung. Dieses Argument ist nur gültig, wenn ALTER EVENT SESSION auf ein Ereignissitzungsobjekt angewendet wird.
ADD EVENT <Ereignisbezeichner>	Ordnet das mit <Ereignisbezeichner> angegebene Ereignis der Ereignissitzung zu.
[event_module_guid] .event_package_name.event_name	Ist der Name eines Ereignisses in einem Ereignispaket, wobei Folgendes gilt: - event_module_guid ist die GUID für das Modul, das das Ereignis enthält. - event_package_name ist das Paket, das das Aktionsobjekt enthält. - event_name ist das Ereignisobjekt. Ereignisse werden in der sys.dm_xe_objects-Sicht als object_type 'event' angezeigt.
SET { event_customizable_attribute= <Wert> [ ,...n] }	Gibt anpassbare Attribute für das Ereignis an. Anpassbare Attribute werden in der sys.dm_xe_object_columns-Sicht mit column_type 'customizable' und object_name = event_name angezeigt.
ACTION ( { [event_module_guid] .event_package_name.action_name [ , ...n] } )	Die Aktion, die mit der Ereignissitzung verknüpft werden soll. Dabei gilt: - event_module_guid ist die GUID für das Modul, das das Ereignis enthält. - event_package_name ist das Paket, das das Aktionsobjekt enthält. - action_name ist das Aktionsobjekt. Aktionen werden in der sys.dm_xe_objects-Sicht als object_type 'action' angezeigt.
WHERE <Prädikatausdruck>	Gibt den Prädikatausdruck an, mit dessen Hilfe bestimmt wird, ob ein Ereignis verarbeitet werden muss. Wenn <Prädikatausdruck> den Wert TRUE hat, wird das Ereignis von den Aktionen und Zielen für die Sitzung weiter verarbeitet. Wenn <predicate_expression> falsch ist, tritt die Aktion und die Zielverarbeitung für dieses Ereignis nicht auf. Die Länge von Prädikatausdrücken ist auf 3.000 Zeichen beschränkt, wodurch die Länge von Zeichenfolgenargumenten eingeschränkt wird.
event_field_name	Ist der Name des Ereignisfelds, das die Prädikatquelle identifiziert.
[event_module_guid].event_package_name.predicate_source_name	Ist der Name der globalen Prädikatquelle, wobei Folgendes gilt: - event_module_guid ist die GUID für das Modul, das das Ereignis enthält. - event_package_name ist das Paket, das das Prädikatobjekt enthält. - predicate_source_name ist in der sys.dm_xe_objects-Sicht als object_type 'pred_source' definiert.
[event_module_guid].event_package_name.predicate_compare_name	Der Name des Prädikatobjekts, das mit dem Ereignis verknüpft werden soll. Dabei gilt Folgendes: - event_module_guid ist die GUID für das Modul, das das Ereignis enthält. - event_package_name ist das Paket, das das Prädikatobjekt enthält. - predicate_compare_name ist eine globale Quelle, die in der sys.dm_xe_objects-Sicht als object_type 'pred_compare' definiert ist.
DROP EVENT <Ereignisbezeichner>	Löscht das mit <Ereignisbezeichner> angegebene Ereignis. <Ereignisbezeichner> muss in der Ereignissitzung gültig sein.
ADD TARGET <Ereigniszielbezeichner>	Ordnet das mit <Ereigniszielbezeichner> angegebene Ziel der Ereignissitzung zu.
[event_module_guid].event_package_name.target_name	Der Name eines Ziels in der Ereignissitzung, wobei Folgendes gilt: - event_module_guid ist die GUID für das Modul, das das Ereignis enthält. - event_package_name ist das Paket, das das Aktionsobjekt enthält. - target_name ist die Aktion. Aktionen werden in der sys.dm_xe_objects-Sicht als object_type 'target' angezeigt.
SET { target_parameter_name= <Wert> [, ...n] }	Legt einen Zielparameter fest. Zielparameter werden in der sys.dm_xe_object_columns-Sicht mit column_type 'customizable' und object_name = target_name angezeigt. Hinweis: Wenn Sie das Ringpufferziel verwenden, empfehlen wir, den max_memory Zielparameter auf 2.048 Kb (KB) festzulegen, um mögliche Datenkürzungen der XML-Ausgabe zu vermeiden. Informationen zur Verwendung von unterschiedlichen Zieltypen finden Sie unter Ziele für erweiterte Ereignisse von SQL Server.
DROP TARGET <Ereigniszielbezeichner>	Löscht das durch <Ereigniszielbezeichner> angegebene Ziel. <Ereigniszielbezeichner> muss in der Ereignissitzung gültig sein.
EVENT_RETENTION_MODE = { ALLOW_SINGLE_EVENT_LOSS \| ALLOW_MULTIPLE_EVENT_LOSS \| NO_EVENT_LOSS }	Gibt den Ereignisbeibehaltungsmodus an, der zum Behandeln von Ereignisverlusten verwendet werden soll. ALLOW_SINGLE_EVENT_LOSS Ein Ereignis der Sitzung darf verloren gehen. Ein einzelnes Ereignis wird nur gelöscht, wenn alle Ereignispuffer gefüllt sind. Wenn bei gefüllten Ereignispuffern nur ein Ereignis verloren geht, sind akzeptable SQL Server-Leistungsmerkmale möglich, während Datenverluste im verarbeiteten Ereignisdatenstrom minimiert werden. ALLOW_MULTIPLE_EVENT_LOSS Volle Ereignispuffer, die mehrere Ereignisse enthalten, dürfen in der Sitzung verloren gehen. Die Anzahl verloren gegangener Ereignisse hängt von der Größe des Speichers, der der Sitzung zugeordnet ist, der Partitionierung des Speichers und der Größe der Ereignisse im Puffer ab. Die Option minimiert die Leistungseinbußen auf dem Server, wenn Ereignispuffer schnell gefüllt werden, jedoch große Mengen von Ereignissen in der Sitzung verloren gehen können. NO_EVENT_LOSS Verluste von Ereignissen sind nicht zulässig. Diese Option stellt sicher, dass alle ausgelösten Ereignisse beibehalten werden. Wenn diese Option verwendet wird, müssen alle Tasks, die Ereignisse auslösen, warten, bis in einem Ereignispuffer Platz verfügbar wird. Dies kann spürbare Leistungsprobleme verursachen, während die Ereignissitzung aktiv ist. Möglicherweise werden Benutzerverbindungen blockiert, während auf das Leeren von Ereignissen aus dem Puffer gewartet wird. Bei Ereignisdateizielen in Azure SQL-Datenbank verhält sich dasselbe wie ALLOW_SINGLE_EVENT_LOSS. Weitere Informationen finden Sie unter EVENT_RETENTION_MODE.
MAX_DISPATCH_LATENCY = { seconds SECONDS \| INFINITE }	Gibt an, wie lange Ereignisse zwischengespeichert werden, bevor sie an Ereignissitzungsziele gesendet werden. Der Latenzzeitwert muss mindestens 1 Sekunde betragen. Mit dem Wert 0 kann jedoch eine INFINITE-Latenzzeit angegeben werden. Standardmäßig ist dieser Wert auf 30 Sekunden festgelegt. seconds SECONDS Die Wartezeit in Sekunden, bevor die Puffer geleert werden und ihr Inhalt an die Ziele gesendet wird. seconds ist eine ganze Zahl. INFINITE Die Puffer werden nur dann geleert und ihr Inhalt an die Ziele gesendet, wenn die Puffer voll sind oder wenn die Ereignissitzung geschlossen wird. Hinweis: MAX_DISPATCH_LATENCY = 0 SECONDS entspricht MAX_DISPATCH_LATENCY = INFINITE.
MAX_EVENT_SIZE =size [ KB \| MB ]	Gibt die maximal zulässige Größe für Ereignisse an. MAX_EVENT_SIZE sollte nur so festgelegt werden, dass einzelne Ereignisse zulässig sind, die größer als MAX_MEMORY sind; wenn sie auf kleiner als MAX_MEMORY festgelegt wird, wird ein Fehler ausgelöst. size ist eine ganze Zahl und kann in Kilobyte (KB) oder Megabyte (MB) angegeben werden. Wenn size in Kilobyte angegeben wird, ist die geringste zulässige Größe 64 KB. Wenn MAX_EVENT_SIZE festgelegt wird, werden zusätzlich zu MAX_MEMORY zwei Puffer von size erstellt. Dies bedeutet, dass der gesamte für die Ereignispufferung verwendete Arbeitsspeicher dem Wert von MAX_MEMORY + 2 * MAX_EVENT_SIZE entspricht.
MEMORY_PARTITION_MODE = { NONE \| PER_NODE \| PER_CPU }	Gibt den Speicherort an, an dem Ereignispuffer erstellt werden. NONE Innerhalb der SQL Server-Instanz werden mehrere Puffer erstellt. PER NODE: Mehrere Puffer werden für jeden NUMA-Knoten erstellt. PER CPU: Mehrere Puffer werden für jede CPU erstellt.
TRACK_CAUSALITY = { ON \| OFF }	Gibt an, ob Kausalität verfolgt wird. Wenn das Verfolgen der Kausalität aktiviert ist, können ähnliche Ereignisse auf anderen Serververbindungen korreliert werden.
STARTUP_STATE = { ON \| OFF }	Gibt an, ob diese Ereignissitzung beim Start von SQL Server automatisch gestartet werden soll. Wenn STARTUP_STATE=ON der Ereignissitzung nur gestartet wird, wenn SQL Server beendet und dann neu gestartet wird. ON = Die Ereignissitzung wird beim Start gestartet. OFF = Die Ereignissitzung wird nicht beim Start gestartet.

Hinweise

Die Argumente und DROP Argumente ADD können nicht in derselben Anweisung verwendet werden.

Berechtigungen

Erfordert die ALTER ANY EVENT SESSION-Berechtigung.

Tipp

SQL Server 2022 hat eine Reihe neuer differenzierterer Berechtigungen für erweiterte Ereignisse eingeführt, weitere Informationen finden Sie im Blog: Neue granulare Berechtigungen für SQL Server 2022 und Azure SQL zur Verbesserung der Einhaltung von PoLP.

Beispiele

Im folgenden Beispiel wird eine Ereignissitzung gestartet, es werden einige Statistiken zur Livesitzung ermittelt, und anschließend werden der vorhandenen Sitzung zwei Ereignisse hinzugefügt.

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

Teilen über

ALTER EVENT SESSION (Transact-SQL)

Syntax

Argumente

Hinweise

Berechtigungen

Beispiele

Siehe auch

Feedback

Zusätzliche Ressourcen