Freigeben über


EREIGNISSITZUNG ERSTELLEN (Transact-SQL)

Gilt für:SQL ServerAzure SQL-DatenbankVerwaltete Azure SQL-InstanzSQL-Datenbank in Microsoft Fabric

Erstellt eine erweiterte Ereignissitzung, die die zu erfassenden Ereignisse, die Ereignissitzungsziele und die Ereignissitzungsoptionen identifiziert.

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

Argumente

event_session_name

Der benutzerdefinierte Name für die Ereignissitzung. event_session_name alphanumerisch ist, kann bis zu 128 Zeichen lang sein, muss innerhalb einer Instanz von SQL Server eindeutig sein und die Regeln für Datenbankbezeichner erfüllen.

AUF { SERVER | DATENBANK }

Bestimmt, ob sich die Ereignissitzung im Kontext des Servers oder der Datenbank befindet.

Azure SQL Database und SQL Database in Microsoft Fabric erfordern DATABASE.

ADD-EREIGNIS [event_module_guid]. event_package_name. event_name

Das Ereignis, das der Ereignissitzung zugeordnet werden soll, 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 Ereignisname.

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

ZIEL HINZUFÜGEN [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 Ziel enthält.
  • event_package_name ist das Paket, das das Ziel enthält.
  • target_name ist der Zielname.

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, indem Sie den Zielnamen ersetzen target-name-placeholder , z event_file. B. , , ring_bufferusw histogram.:

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

Wichtig

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

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 Ereignisstream 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 Ereignisdatei-Ziele in Azure SQL Database, SQL-Datenbank in Microsoft Fabric und Azure SQL Managed Instance (mit der SQL Server 2025- oder Always-up-to-Date-Update-Policy) NO_EVENT_LOSS verhalten sich ab Juni 2024 gleich 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 die Entfernung als unterstütztes EVENT_RETENTION_MODE Argument in zukünftigen Updates für Azure SQL Database, SQL Database in Microsoft Fabric und Azure SQL Managed Instance geplant. Nutzen Sie diese Funktionen bei Neuentwicklungen nicht mehr, und planen Sie die Änderung von Anwendungen, die diese Funktion zurzeit 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.

  • NachschlagSECONDS

    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 Kausalität verfolgt 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 beim Start von SQL Server automatisch gestartet werden soll.

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

    Erstellt eine Ereignissitzung, die unbegrenzt ausgeführt wird, bis die Verwendung der ALTER EVENT SESSION ... STATE = STOP Anweisung beendet wurde. Dies ist die Standardeinstellung, wenn MAX_DURATION sie nicht angegeben ist.

  • Zeitdauer SEKUNDEN | MINUTEN | STUNDEN | TAGE

    Erstellt eine Ereignissitzung, die 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 Rangfolge der logischen Operatoren beginnt mit NOT (höchster Operator). Darauf folgt AND und anschließend OR.

Berechtigungen

SQL Server und Azure SQL Managed Instance erfordern die CREATE ANY EVENT SESSION (in SQL Server 2022 eingeführt) oder ALTER ANY EVENT SESSION die Berechtigung.

Azure SQL Database und SQL Database in Microsoft Fabric erfordern die CREATE 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. Beispiel für SQL Server und Azure SQL Managed Instance

Das folgende Beispiel zeigt, wie eine Ereignissitzung mit der Bezeichnung test_session erstellt wird. In diesem Beispiel werden zwei Ereignisse hinzugefügt und das event_file Ziel verwendet, wobei die Größe jeder Datei auf 256 MB beschränkt und die beibehaltene Anzahl von Dateien auf 10 beschränkt wird.

IF EXISTS (SELECT 1
           FROM sys.server_event_sessions
           WHERE name = 'test_session')
    DROP EVENT SESSION test_session ON SERVER;

CREATE EVENT SESSION test_session ON SERVER
ADD EVENT sqlserver.rpc_starting,
ADD EVENT sqlserver.sql_batch_starting,
ADD EVENT sqlserver.error_reported
ADD TARGET package0.event_file
    (
    SET filename = N'C:\xe\test_session.xel',
        max_file_size = 256,
        max_rollover_files = 10
    )
WITH (MAX_MEMORY = 4 MB);

B. Beispiele für Azure SQL-Datenbank

Beispiele für exemplarische Vorgehensweisen: Erstellen einer Ereignissitzung mit einem event_file Ziel in Azure Storage und Erstellen einer Ereignissitzung mit einem ring_buffer Ziel im Arbeitsspeicher.

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

Einige Transact-SQL Codebeispiele, die für SQL Server geschrieben wurden, benötigen kleine Änderungen für die Ausführung in Azure SQL-Datenbank oder SQL-Datenbank in Fabric. 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, SQL-Datenbank in Fabric und SQL Managed Instance

Azure SQL-Datenbank und SQL-Datenbank in Fabric unterstützen nur Datenbank-bezogene Ereignissitzungen. SQL Server Management Studio (SSMS) unterstützt Datenbank-bezogene Ereignissitzungen für Azure SQL-Datenbank: Ein Knoten mit erweiterten Ereignissen mit Datenbankbereichssitzungen 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

Serverweite Ereignissitzungen werden für azure SQL Managed Instance empfohlen.

Ereignissitzungen mit Datenbankbereich werden im Objekt-Explorer in SSMS für verwaltete Azure SQL-Instanz nicht angezeigt. In einer von SQL verwalteten Instanz können Ereignissitzungen mit Datenbankbereich nur mit Transact-SQL abgefragt und verwaltet werden.

Zur Veranschaulichung werden in der folgenden Tabelle zwei Teilmengen der Katalogsichten aufgelistet und verglichen. 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, SQL-Datenbank in Fabric und azure SQL Managed Instance
sys.server_event_session_actions
sys.server_event_session_events
sys.server_event_session_fields
sys.server_event_session_targets
sys.server_event_sessions
sys.database_event_session_actions
sys.database_event_session_events
sys.database_event_session_fields
sys.database_event_session_targets
sys.database_event_sessions