CREATE EVENT SESSION (Transact-SQL)

  • Artikel

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

Themenlink (Symbol) Transact-SQL-Syntaxkonventionen

Syntax

CREATE EVENT SESSION event_session_name
ON SERVER
{
    <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 des Moduls, welches das Ereignis enthält.

    • Das Paket event_package_name enthält das Aktionsobjekt.

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

  • number
    Ist jeder numerische 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'
    Entweder 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 des Moduls, das das Ereignis enthält.

    • Das Paket event_package_name enthält das Aktionsobjekt.

    • target_name ist das Ziel. Ziele werden in der sys.dm_xe_objects-Sicht als 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.

    Wichtiger HinweisWichtig

    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.

  • WITH (<Ereignissitzungsoptionen> [ ,...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. Die Standardeinstellung ist 4 MB. size ist eine ganze Zahl und kann in Kilobyte (KB) oder Megabyte (MB) angegeben werden.

  • 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. 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 wenn die Ereignissitzung geschlossen wird.

      HinweisHinweis

      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.

    HinweisHinweis

    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 nicht beim Start gestartet.

Hinweise

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

Berechtigungen

Erfordert die ALTER ANY EVENT SESSION-Berechtigung.

Beispiele

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

Siehe auch

Verweis

ALTER EVENT SESSION (Transact-SQL)

DROP EVENT SESSION (Transact-SQL)

sys.server_event_sessions (Transact-SQL)

sys.dm_xe_objects (Transact-SQL)

sys.dm_xe_object_columns (Transact-SQL)