ALTER EVENT SESSION (Transact-SQL)

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 | DATABASE }
{
    [ [ {  <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 } ]
    [ [ , ] MAX_DURATION = { <time duration> { SECONDS | MINUTES | HOURS | DAYS } | UNLIMITED } ]
}

Argumente

event_session_name

Der Name einer vorhandenen Ereignissitzung.

STATE = START | AUFHÖREN

Startet oder beendet die Ereignissitzung. Das STATE Argument muss eigenständig angegeben werden. Sie kann nicht mit anderen Argumenten in derselben ALTER EVENT SESSION Anweisung kombiniert werden.

ADD EVENT <Ereignisbezeichner>

Identifiziert ein Ereignis, das der Ereignissitzung zugeordnet werden soll. < > event_specifier ist in Form von [event_module_guid].event_package_name. event_name, wobei:

event_module_guid ist die GUID für das Modul, das das Ereignis enthält.
event_package_name ist das Paket, das das Ereignis enthält.
event_name ist der Name des Ereignisses.

Verfügbare Ereignisse können durch Ausführen der folgenden Abfrage gefunden werden:

SELECT o.name AS event_name,
       o.description AS event_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'event'
ORDER BY event_name ASC;

SET { event_customizable_attribute = <Wert> [ ,... n ] }

Anpassbare Attribute für das Ereignis.

Anpassbare Attribute für ein bestimmtes Ereignis finden Sie, indem Sie die folgende Abfrage ausführen:

SELECT object_name,
       name AS column_name,
       type_name,
       column_value,
       description
FROM sys.dm_xe_object_columns
WHERE object_name = 'event-name-placeholder'
      AND column_type = 'customizable'
ORDER BY column_name ASC;

ACTION ( { [event_module_guid].event_package_name. action_name [ ,... n ] })

Die Aktion, die dem Ereignis zugeordnet werden soll, wobei:

event_module_guid ist die GUID für das Modul, das die Aktion enthält.
event_package_name ist das Paket, das die Aktion enthält.
action_name ist der Name der Aktion.

Verfügbare Aktionen können durch Ausführen der folgenden Abfrage gefunden werden:

SELECT o.name AS action_name,
       o.description AS action_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'action'
ORDER BY action_name ASC;

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> "false" ist, wird das Ereignis verworfen und verhindert, dass zusätzliche Aktionen und Zielverarbeitungen ausgeführt werden. Jeder Prädikatausdruck ist auf 3.000 Zeichen beschränkt.

event_field_name

Der Name des Ereignisfelds, das die Prädikatquelle identifiziert.

Die Felder für ein Ereignis finden Sie, indem Sie die folgende Abfrage ausführen:

SELECT oc.name AS field_name,
       oc.type_name AS field_type,
       oc.description AS field_description
FROM sys.dm_xe_objects AS o
INNER JOIN sys.dm_xe_packages AS p
ON o.package_guid = p.guid
INNER JOIN sys.dm_xe_object_columns AS oc
ON o.name = oc.object_name
   AND
   o.package_guid = oc.object_package_guid
WHERE o.object_type = 'event'
      AND
      o.name = 'event-name-placeholder'
      AND
      oc.column_type = 'data'
ORDER BY field_name ASC;

[event_module_guid]. event_package_name. predicate_source_name

Der Name der globalen Prädikatquelle, wobei:

event_module_guid ist die GUID für das Modul, das das Ereignis enthält.
event_package_name ist das Paket, das das Prädikatquellobjekt enthält.
predicate_source_name ist der Name der Prädikatquelle.

Prädikatquellen können durch Ausführen der folgenden Abfrage gefunden werden:

SELECT o.name AS predicate_source_name,
       o.description AS predicate_source_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'pred_source'
ORDER BY predicate_source ASC;

[event_module_guid].event_package_name.predicate_compare_name

Der Name des Prädikatkomparatorobjekts, wobei:

event_module_guid ist die GUID für das Modul, das das Ereignis enthält.
event_package_name ist das Paket, das das Prädikatkomparatorobjekt enthält.
predicate_compare_name ist der Prädikatvergleichsname.

Prädikatkomparatoren können durch Ausführen der folgenden Abfrage gefunden werden:

SELECT o.name AS predicate_comparator_name,
       o.description AS predicate_comparator_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'pred_compare'
ORDER BY predicate_comparator ASC;

number

Jeder numerische Typ, der als 64-Bit-Ganzzahl dargestellt werden kann.

'string'

Entweder eine ANSI- oder Unicode-Zeichenfolge, die vom Prädikatkomparator benötigt wird. Für die Prädikatvergleichsfunktionen wird keine implizite Zeichenfolgentypkonvertierung ausgeführt. Das Übergeben des Werts eines unerwarteten Typs führt zu einem Fehler.

DROP EVENT <Ereignisbezeichner>

Identifiziert ein Ereignis, das aus der Ereignissitzung entfernt werden soll. Der Ereignisbezeichner ist in Form von [event_module_guid]. event_package_name. event_name, wobei:

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.

< > event_specifier muss ein Ereignis identifizieren, das zuvor der Ereignissitzung hinzugefügt wurde.

ADD TARGET <Ereigniszielbezeichner>

Identifiziert ein Ziel, das einer Ereignissitzung zugeordnet werden soll. Der Ereigniszielbezeichner ist in Form von [event_module_guid]. event_package_name. target_name, wobei:

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 der Name des Ziels.

Verfügbare Ziele können durch Ausführen der folgenden Abfrage gefunden werden:

SELECT o.name AS target_name,
       o.description AS target_description,
       o.capabilities_desc,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'target'
ORDER BY target_name ASC;

Eine Ereignissitzung kann null, eins oder viele Ziele aufweisen. Alle Ziele, die einer Ereignissitzung hinzugefügt werden, müssen unterschiedlich sein. Beispielsweise können Sie einer Sitzung, die bereits über ein event_file Ziel verfügt, kein zweites event_file Ziel hinzufügen.

Weitere Informationen, einschließlich Verwendungsbeispiele für häufig verwendete Ziele, finden Sie unter "Erweiterte Ereignisse"-Ziele.

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

Legt einen Zielparameter fest.

Um alle Zielparameter und deren Beschreibungen anzuzeigen, führen Sie die folgende Abfrage aus, und ersetzen target-name-placeholder Sie dabei den Zielnamen, zevent_file. B. , , ring_bufferhistogramusw.

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-placeholder';

Von Bedeutung

Wenn Sie das Ringpufferziel verwenden, empfehlen wir, den MAX_MEMORYZielparameter (getrennt vom MAX_MEMORYSitzungsparameter ) auf 1.024 KB (KB) festzulegen, um mögliche Datenkürzungen der XML-Ausgabe zu vermeiden.

Weitere Informationen zu Zieltypen finden Sie unter "Extended Events targets".

DROP TARGET <Ereigniszielbezeichner>

Identifiziert ein Ziel, das aus einer Ereignissitzung entfernt werden soll. Der Ereigniszielbezeichner ist in Form von [event_module_guid]. event_package_name. target_name, wobei:

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 der Name des Ziels.

Der Ereigniszielbezeichner muss ein Ziel identifizieren, das zuvor der Ereignissitzung hinzugefügt wurde.

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

Gibt die Optionen an, die mit der Ereignissitzung verwendet werden sollen.

MAX_MEMORY = Größe [ KB | MB ]

Gibt an, wieviel Arbeitsspeicher der Sitzung für die Ereignispufferung maximal zugeordnet werden soll. Der Standardwert ist 4 MB. size ist eine ganze Zahl und kann in Kilobyte (KB) oder Megabyte (MB) angegeben werden. Der maximal zulässige Betrag darf 2 GB (2.048 MB) nicht überschreiten. Die Verwendung von Speicherwerten im GB-Bereich wird jedoch nicht empfohlen.

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. Der Verlust eines einzelnen Ereignisses, wenn Ereignispuffer vollständig sind, minimiert die Leistungseinbußen, während gleichzeitig der Verlust von Daten im verarbeiteten Ereignisdatenstrom minimiert wird.
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. Diese Option vermeidet in der Regel Leistungseinbußen auf den Server, wenn Ereignispuffer schnell gefüllt werden, aber eine große Anzahl von Ereignissen kann aus der Sitzung verloren gehen.
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. Die Verwendung von NO_EVENT_LOSS kann zu erkennbaren Leistungsproblemen führen, während die Ereignissitzung aktiv ist. Benutzersitzungen und Abfragen können während des Wartens, dass Ereignisse aus dem Puffer geleert werden, angehalten werden.

Hinweis

Für die Ereignisdateiziele in der Azure SQL-Datenbank und in der von Azure SQL verwalteten Instanz (mit der SQL Server 2025- oder Always-up-to-Datumsaktualisierungsrichtlinie) verhält sich ab Juni 2024 NO_EVENT_LOSS dasselbe wie .ALLOW_SINGLE_EVENT_LOSS Wenn Sie angeben NO_EVENT_LOSS, wird eine Warnung mit nachrichten-ID 25665, Schweregrad 10 und Nachricht This target doesn't support the NO_EVENT_LOSS event retention mode. The ALLOW_SINGLE_EVENT_LOSS retention mode is used instead. zurückgegeben, und die Sitzung wird erstellt.

Diese Änderung vermeidet Verbindungstimeouts, Failoververzögerungen und andere Probleme, die die Datenbankverfügbarkeit verringern können, wenn NO_EVENT_LOSS sie mit Ereignisdateizielen im Azure Blob Storage verwendet wird.

NO_EVENT_LOSS ist für das Entfernen als unterstütztes EVENT_RETENTION_MODE Argument in zukünftigen Updates für Azure SQL-Datenbank und azure SQL Managed Instance geplant. Vermeiden Sie die Verwendung dieses Features in neuer Entwicklungsarbeit, und planen Sie, Anwendungen zu ändern, die derzeit dieses Feature verwenden.

MAX_DISPATCH_LATENCY = { Sekunden | INFINITE }

Gibt an, wie lange Ereignisse zwischengespeichert werden, bevor sie an Ereignissitzungsziele gesendet werden. Standardmäßig ist dieser Wert auf 30 Sekunden festgelegt.

Nachschlag NACHSCHLAG

Die Wartezeit in Sekunden, bevor die Puffer geleert werden und ihr Inhalt an die Ziele gesendet wird. seconds ist eine ganze Zahl. Der Latenzzeitwert muss mindestens 1 Sekunde betragen. Mit dem Wert 0 kann jedoch eine INFINITE-Latenzzeit angegeben werden.
UNENDLICH

Die Puffer werden nur dann geleert und ihr Inhalt an die Ziele gesendet, wenn die Puffer voll sind oder wenn die Ereignissitzung geschlossen wird.

MAX_EVENT_SIZE = Größe [ 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 der Größe erstellt, und der für die Ereignispufferung verwendete Gesamtspeicher wird MAX_MEMORY + 2 * MAX_EVENT_SIZE.

MEMORY_PARTITION_MODE = { KEINE | PER_NODE | PER_CPU }

Gibt die Affinität von Ereignispuffern an. Andere Optionen als NONE die Folge von mehr Puffern und einer höheren Arbeitsspeicherauslastung, können jedoch Konflikte vermeiden und die Leistung auf größeren Computern verbessern.

NICHTS

Eine einzelne Gruppe von Puffern wird in der Datenbankmodulinstanz erstellt.
PER_NODE

Für jeden NUMA-Knoten wird eine Reihe von Puffern erstellt.
PER_CPU

Ein Satz von Puffern wird für jede CPU erstellt.

TRACK_CAUSALITY = { ON | FALSCH }

Gibt an, ob die Ereignisursache nachverfolgt wird. Wenn das Verfolgen der Kausalität aktiviert ist, können ähnliche Ereignisse auf anderen Serververbindungen korreliert werden.

STARTUP_STATE = { ON | FALSCH }

Gibt an, ob diese Ereignissitzung automatisch gestartet werden soll, wenn das Datenbankmodul gestartet wird.

Hinweis

Wenn STARTUP_STATE = ONdie Ereignissitzung gestartet wird, wenn das Datenbankmodul beendet und dann neu gestartet wird. Um die Ereignissitzung sofort zu starten, verwenden Sie ALTER EVENT SESSION ... ON SERVER STATE = START.

EIN

Die Ereignissitzung wird beim Start gestartet.
OFF

Die Ereignissitzung wird beim Start nicht gestartet.

MAX_DURATION = { Zeitdauer { SECONDS | MINUTEN | STUNDEN | DAYS } | UNLIMITED }

Gilt für: SQL Server 2025 (17.x)

UNBEGRENZT

Bewirkt, dass eine Ereignissitzung unbegrenzt ausgeführt wird, sobald sie gestartet wurde, bis die Verwendung der ALTER EVENT SESSION ... STATE = STOP Anweisung beendet wurde.
Zeitdauer SEKUNDEN | MINUTEN | STUNDEN | TAGE

Bewirkt, dass eine Ereignissitzung nach ablaufen der angegebenen Zeit nach dem Start der Sitzung automatisch beendet wird. Die maximale unterstützte Dauer beträgt 2.147.483 Sekunden oder 35.792 Minuten oder 596 Stunden oder 24 Tage.

Weitere Informationen finden Sie unter "Zeitgebundene Ereignissitzungen".

Hinweise

Weitere Informationen zu Ereignissitzungsargumenten finden Sie unter "Erweiterte Ereignissitzungen".

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

Berechtigungen

SQL Server und Azure SQL Managed Instance erfordern die ALTER ANY EVENT SESSION Berechtigung.

Azure SQL-Datenbank erfordert die ALTER ANY DATABASE EVENT SESSION Berechtigung in der Datenbank.

Tipp

SQL Server 2022 hat genauere 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

A. Starten und Beenden einer Ereignissitzung

Ersetzen Sie zum Verwenden dieses Beispiels mit Datenbankereignissitzungen ON SERVER durch ON DATABASE.

ALTER EVENT SESSION test_session ON SERVER STATE = START;
ALTER EVENT SESSION test_session ON SERVER STATE = STOP;

B. Hinzufügen neuer Ereignisse zu einer vorhandenen Sitzung