• Artikel

ALTER EVENT SESSION (Transact-SQL)

Beginnt oder beendet eine Ereignissitzung oder ändert eine Ereignissitzungskonfiguration.

Themenlink (Symbol)Transact-SQL-Syntaxkonventionen

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

Ausdruck

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 <event_specifier>bestimmte 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 des Moduls, welches das Ereignis enthält.

  • event_package_name ist das Paket, welches 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] } )

Ist die Aktion, die mit der Ereignissitzung zu verknüpfen ist. Dabei gilt:

  • event_module_guid ist die GUID des Moduls, 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 festgestellt 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 <Prädikatausdruck> den Wert false hat, wird das Ereignis von der Sitzung gelöscht, bevor es von den Aktionen und Zielen für die Sitzung verarbeitet wird. Die Länge von Prädikatausdrücken ist auf 3000 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 des Moduls, 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

Ist der Name des Prädikatobjekts, das mit dem Ereignis zu verknüpfen ist. Dabei gilt Folgendes:

  • event_module_guid ist die GUID des Moduls, 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 <event_specifier> bestimmte Ereignis. <Ereignisbezeichner> muss in der Ereignissitzung gültig sein.

ADD TARGET <Ereigniszielbezeichner>

Ordnet das mit <event_target_specifier>bestimmte Ziel der Ereignissitzung zu.

[event_module_guid].event_package_name.target_name

Ist der Name eines Ziels in der Ereignissitzung, wobei Folgendes gilt:

  • event_module_guid ist die GUID des Moduls, 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.

Wichtiger HinweisWichtig
Wenn Sie ein Ringpufferziel verwenden, sollten Sie den max_memory-Zielparameter auf 2048 Kilobytes (KB) festlegen, um ein mögliches Abschneiden der Daten in der XML-Ausgabe zu vermeiden. Weitere Informationen über die Verwendung unterschiedlicher Zieltypen finden Sie unter SQL Server Extended Events-Ziele.

DROP TARGET <Ereigniszielbezeichner>

Löscht das mit <Ereigniszielbezeichner> bestimmte 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 Ereignisstrom 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 ab, der der Sitzung zugeordnet ist, der Partitionierung des Speichers und der Größe der Ereignisse im Puffer. 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.

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.

HinweisHinweis
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 festgelegt werden, um einzelne Ereignisse zuzulassen, deren Wert den von MAX_MEMORY überschreitet. Ist der festgelegte Wert kleiner als der von MAX_MEMORY, 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 minimal zulässige Größe 64&nbsp;KB. Wenn MAX_EVENT_SIZE festgelegt wird, werden zusätzlich zu MAX_MEMORY zwei Puffer der Größe 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 Ort an, an dem Ereignispuffer erstellt werden.

NONE

Innerhalb der SQL Server-Instanz wird ein einzelner Satz von Puffern erstellt.

PER_NODEEin Satz von Puffern wird für jeden NUMA-Knoten erstellt. Weitere Informationen finden Sie unter Grundlegendes zu NUMA (Non-Uniform Memory Access).
PER_CPUEin Satz von Puffern wird 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.

HinweisHinweis
Wenn STARTUP_STATE = ON, beginnt die Ereignissitzung erst, wenn SQL Server beendet und anschließend neu gestartet wird.
BegriffDefinition
ONDie Ereignissitzung wird beim Start gestartet.
OFFDie Ereignissitzung wird nicht beim Start gestartet.

Hinweise

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

Berechtigungen

Erfordert die CONTROL SERVER-Berechtigung.

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

Änderungsverlauf

Aktualisierter Inhalt

Der Standardwert für das MAX_DISPATCH_LATENCY-Argument wurde korrigiert.

Ein wichtiger Hinweis zur Beschreibung für SET { target_parameter_name = <Wert> [, ...n] wurde hinzugefügt. }.