CREATE EVENT SESSION (Transact-SQL)

Gilt für:SQL ServerAzure SQL-DatenbankAzure 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';

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.

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.

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.

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 Managed Instance ist die ALTER ANY EVENT SESSION-Berechtigung erforderlich. In der SQL-Datenbank ist die ALTER ANY DATABASE EVENT SESSION-Berechtigung für die Datenbank erforderlich.

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.

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.

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

• sys.server_event_sessions (Transact-SQL)
• sys.dm_xe_objects (Transact-SQL)
• sys.dm_xe_object_columns (Transact-SQL)

Nächste Schritte

• ALTER EVENT SESSION (Transact-SQL)
• DROP EVENT SESSION (Transact-SQL)