Freigeben über

CREATE EVENT SESSION (Transact-SQL)

  • Artikel

Gilt für: SQL Server Azure SQL-Datenbank Azure SQL Managed Instance

Erstellt eine Sitzung für erweiterte Ereignisse, die die Quelle der Ereignisse, die Ereignissitzungsziele und die Ereignissitzungsoptionen bestimmt.

Transact-SQL-Syntaxkonventionen

Syntax

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

Argumente

event_session_name

Der benutzerdefinierte Name für die Ereignissitzung. event_session_name ist alphanumerisch, kann bis zu 128 Zeichen enthalten, muss innerhalb einer Instanz von SQL Server eindeutig sein und muss den Regeln für Bezeichner entsprechen.

ADD EVENT [ event_module_guid ].event_package_name.event_name

Ist das Ereignis, das mit der Ereignissitzung zu verknüpfen ist. 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.
  • event_name ist das Ereignisobjekt.

Ereignisse werden in der sys.dm_xe_objects-Sicht als object_type 'event' angezeigt.

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

Ermöglicht die Festlegung anpassbarer Attribute für das Ereignis. 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.

Ereignisse werden in der sys.dm_xe_objects-Sicht als object_type 'action' angezeigt.

WHERE <predicate_expression>

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. Prädikatausdrücke sind auf 3.000 Zeichen beschränkt.

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. 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 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 dem Ereignis zugeordnet 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 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.

number ist ein beliebiger numerischer Typ einschließlich decimal. Einschränkungen stellen der verfügbare physische Speicher oder eine Zahl dar, die zu groß ist, um als 64-Bit-Ganzzahl dargestellt werden zu können.

string ist eine ANSI- oder Unicode-Zeichenfolge, die vom Prädikatvergleich verlangt wird. Für die Prädikatvergleichsfunktionen wird keine implizite Zeichenfolgentypkonvertierung ausgeführt. Die Übergabe des falschen Typs führt zu einem Fehler.

ADD TARGET [event_module_guid].event_package_name.target_name

Ist das Ziel, das mit der Ereignissitzung zu verknüpfen ist. 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.
  • target_name ist das Ziel. Ziele werden in der sys.dm_xe_objects-Sicht als object_type 'target' angezeigt.

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

Legt einen Zielparameter fest.

Um alle Zielparameter und deren Beschreibungen anzuzeigen, führen Sie die folgende Abfrage aus, indem Sie den target-name Platzhalter durch den Zielnamen ersetzen, z event_file. B. , , ring_buffer, histogramusw.

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

Wichtig

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

Weitere Informationen zu Zieltypen finden Sie unter Targets for Extended Events in SQL Server.

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

Gibt Optionen an, die für die Ereignissitzung verwendet werden.

MAX_MEMORY =size [ 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 (kleiner als 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. 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 unzulä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. Möglicherweise werden Benutzerverbindungen blockiert, während auf das Leeren von Ereignissen aus dem Puffer gewartet wird.

Hinweis

Für die Ereignisdateiziele in Azure SQL-Datenbank und in Azure SQL verwaltete Instanz mit der immer aktuellen Updaterichtlinie ab Juni 2024 verhält sich NO_EVENT_LOSS wie ALLOW_SINGLE_EVENT_LOSS. Wenn Sie NO_EVENT_LOSS angeben, wird eine Warnung mit nachrichten-ID 25665, Schweregrad 10 und Meldung Dieses Ziel unterstützt nicht den NO_EVENT_LOSS Ereignisaufbewahrungsmodus. Stattdessen wird der ALLOW_SINGLE_EVENT_LOSS Aufbewahrungsmodus verwendet. wird 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 mit Ereignisdateizielen in Azure Blob Storage verwendet wird.

NO_EVENT_LOSS werden als unterstütztes EVENT_RETENTION_MODE-Argument in zukünftigen Updates für Azure SQL-Datenbank und Azure SQL verwaltete Instanz entfernt. Nutzen Sie diese Funktionen bei Neuentwicklungen nicht mehr, und planen Sie die Änderung von Anwendungen, die diese Funktion zurzeit verwenden.

MAX_DISPATCH_LATENCY = { seconds SECONDS | INFINITE }

Gibt an, wie lange Ereignisse zwischengespeichert werden, bevor sie an Ereignissitzungsziele gesendet 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. Der Latenzzeitwert muss mindestens 1 Sekunde betragen. Mit dem Wert 0 kann jedoch eine INFINITE-Latenzzeit angegeben werden.

INFINITE: Die Puffer werden nur dann geleert und ihr Inhalt an die Ziele gesendet, wenn die Puffer voll sind oder 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 der Größe erstellt, und der für die Ereignispufferung verwendete Gesamtspeicher wird MAX_MEMORY + 2 * MAX_EVENT_SIZE.

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

Hinweis

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

ON: Die Ereignissitzung wird beim Start gestartet.

OFF Die Ereignissitzung wird beim Start nicht gestartet.

Hinweise

Die Rangfolge der logischen Operatoren beginnt mit NOT (höchster Operator). Darauf folgt AND und anschließend OR.

Berechtigungen

Für SQL Server und SQL-verwaltete Instanz ist die CREATE ANY EVENT SESSION (in SQL Server 2022 eingeführte) oder ALTER ANY EVENT SESSION Berechtigung erforderlich.

In der SQL-Datenbank ist die ALTER ANY DATABASE EVENT SESSION-Berechtigung für die Datenbank erforderlich.

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

SQL Server-Beispiel

Das folgende Beispiel zeigt, wie eine Ereignissitzung mit der Bezeichnung test_session erstellt wird. In diesem Beispiel werden zwei Ereignisse hinzugefügt, und das Ziel 'Ereignisablaufverfolgung für Windows' wird verwendet.

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

Azure SQL-Beispiel

Speichern Sie in Azure SQL Managed Instance oder Azure SQL-Datenbank XEL-Dateien in Azure Blob Storage. Sie können mit sys.fn_xe_file_target_read_file aus erweiterten Ereignissitzungen lesen, die Sie selbst erstellen und in Azure Blob Storage speichern können. Exemplarische Vorgehensweise finden Sie unter Ereignisdatei-Zielcode für erweiterte Ereignisse in Azure SQL-Datenbank und Azure SQL Managed Instance.

Codebeispiele können sich für Azure SQL-Datenbank und SQL Managed Instance unterscheiden.

Einige Transact-SQL-Codebeispiele, die für SQL Server-Instanzen geschrieben wurden, müssen leicht abgeändert werden, damit sie in Azure ausgeführt werden können. Eine Kategorie solcher Codebeispiele umfasst Katalogansichten, deren Namenspräfixe je nach Datenbank-Engine-Typ unterschiedlich sind:

  • server_ - Präfix für SQL Server und Azure SQL Managed Instance
  • database_ - Präfix für Azure SQL-Datenbank und SQL Managed Instance

Azure SQL-Datenbank unterstützt nur Ereignissitzungen auf Datenbankebene. SQL Server Management Studio (SSMS) unterstützt datenbankbezogene Ereignissitzungen für Azure SQL-Datenbank vollständig: der Knoten Erweiterte Ereignisse mit datenbankbezogenen Sitzungen wird unter jeder Datenbank im Objekt-Explorer angezeigt.

Azure SQL Managed Instance unterstützt sowohl datenbankbezogene Sitzungen als auch serverbezogene Sitzungen. SSMS unterstützt vollständig serverbezogene Sitzungen für SQL Managed Instance: Der Knoten Erweiterte Ereignisse mit allen serverbezogenen Sitzungen wird unter dem Ordner Verwaltung für jede verwaltete Instanz im Objekt-Explorer angezeigt.

Hinweis

Serverbezogene Sitzungen werden für verwaltete Instanzen empfohlen. Datenbankbezogene Sitzungen werden im Objekt-Explorer in SSMS für Azure SQL Managed Instance nicht angezeigt. Datenbankbezogene Sitzungen können nur mit Transact-SQL bei Verwendung einer verwalteten Instanz abgefragt und verwaltet werden.

Zur Veranschaulichung werden in der folgenden Tabelle zwei Teilmengen der Katalogsichten aufgelistet und verglichen. Aus Platzgründen sind diese Teilmengen auf Sichtnamen beschränkt, die auch die Zeichenfolge _event enthalten. Die Namenspräfixe der Teilmengen unterscheiden sich, da sie unterschiedliche Datenbank-Engine-Typen unterstützen.

Name in SQL Server und Azure SQL Managed Instance Name in Azure SQL-Datenbank und Azure SQL Managed Instance
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

Die beiden Listen in der vorangehenden Tabelle zeigen den Stand von März 2022. Führen Sie die folgende SELECT-Anweisung (Transact-SQL) aus, um eine aktuelle Liste zu erhalten:

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;

Siehe auch

Nächste Schritte