ALTER EVENT SESSION (Transact-SQL)

Artikel
06/18/2013

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

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

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 <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, 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 als 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 des Moduls, das das Ereignis enthält.
Das Paket event_package_name enthält das Aktionsobjekt.
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 <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 Sicht sys.dm_xe_objects 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 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. <event_specifier> 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

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

Wichtig
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 Ziele für erweiterte Ereignisse von SQL Server.

DROP TARGET <Ereigniszielbezeichner>

Löscht das durch <event_target_specifier> angegebene Ziel. <event_target_specifier> 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 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.

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 so festgelegt werden, dass nur einzelne Ereignisse zugelassen werden, 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 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 Speicherort an, an dem Ereignispuffer erstellt werden.

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

PER_NODE	Ein Satz von Puffern wird für jeden NUMA-Knoten erstellt.
PER_CPU	Ein 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.

Hinweis
Wenn STARTUP_STATE = ON, beginnt die Ereignissitzung erst, wenn SQL Server beendet und anschließend neu gestartet wird.

Begriff	Definition
ON	Die Ereignissitzung wird beim Start gestartet.
OFF	Die Ereignissitzung wird nicht beim Start gestartet.

Hinweise

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

Berechtigungen

Erfordert die ALTER ANY EVENT SESSION-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