CREATE EVENT SESSION (Transact-SQL)CREATE EVENT SESSION (Transact-SQL)

DIESES THEMA GILT FÜR:jaSQL Server (ab 2008)jaAzure SQL-DatenbankneinAzure SQL Data Warehouse neinParallel Data Warehouse THIS TOPIC APPLIES TO:yesSQL Server (starting with 2008)yesAzure SQL DatabasenoAzure SQL Data Warehouse noParallel Data Warehouse

Erstellt eine Sitzung für erweiterte Ereignisse, die die Quelle der Ereignisse, die Ereignissitzungsziele und die Ereignissitzungsoptionen bestimmt.Creates an Extended Events session that identifies the source of the events, the event session targets, and the event session options.

Symbol für Themenlink Transact-SQL-Syntaxkonventionen.Topic link icon Transact-SQL Syntax Conventions.

SyntaxSyntax


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

ArgumenteArguments

event_session_nameevent_session_name
Der benutzerdefinierte Name für die Ereignissitzung.Is the user-defined name for the event session. Event_session_name ist alphanumerisch, kann bis zu 128 Zeichen sein, muss innerhalb einer Instanz eindeutig sein SQL ServerSQL Server, und Sie müssen den Regeln für entsprechen Bezeichner.event_session_name is alphanumeric, can be up to 128 characters, must be unique within an instance of SQL ServerSQL Server, and must comply with the rules for Identifiers.

ADD EVENT [ Event_module_guid ]. Event_package_name. EreignisnameADD EVENT [ event_module_guid ].event_package_name.event_name
Ist das Ereignis, das mit der Ereignissitzung zu verknüpfen ist. Dabei gilt:Is the event to associate with the event session, where:

  • Event_module_guid ist die GUID für das Modul, das das Ereignis enthält.event_module_guid is the GUID for the module that contains the event.

  • Event_package_name ist das Paket, das das Aktionsobjekt enthält.event_package_name is the package that contains the action object.

  • Ereignisname ist das Ereignisobjekt.event_name is the event object.

    Ereignisse werden in der sys.dm_xe_objects-Sicht als object_type 'event' angezeigt.Events appear in the sys.dm_xe_objects view as object_type 'event'.

    Legen Sie { Event_customizable_attribute= <Wert > [,... n] }SET { event_customizable_attribute= <value> [ ,...n] }
    Ermöglicht die Festlegung anpassbarer Attribute für das Ereignis.Allows customizable attributes for the event to be set. Anpassbare Attribute werden in der dm_xe_object_columns-Sicht mit Column_type 'customizable' und Object_name = Event_name.Customizable attributes appear in the sys.dm_xe_object_columns view as column_type 'customizable ' and object_name = event_name.

    Aktion ({[Event_module_guid]. Event_package_name. Aktionsname [ ,... n] })ACTION ( { [event_module_guid].event_package_name.action_name [ ,...n] })
    Die Aktion, die mit der Ereignissitzung verknüpft werden soll. Dabei gilt:Is the action to associate with the event session, where:

  • Event_module_guid ist die GUID für das Modul, das das Ereignis enthält.event_module_guid is the GUID for the module that contains the event.

  • Event_package_name ist das Paket, das das Aktionsobjekt enthält.event_package_name is the package that contains the action object.

  • Aktionsname ist das Aktionsobjekt.action_name is the action object.

    Aktionen werden in der sys.dm_xe_objects-Sicht als object_type 'action' angezeigt.Actions appear in the sys.dm_xe_objects view as object_type 'action'.

    WOBEI <Prädikatausdruck > Gibt an, der Prädikatausdruck verwendet, um zu bestimmen, ob ein Ereignis verarbeitet werden sollen.WHERE <predicate_expression> Specifies the predicate expression used to determine if an event should be processed. Wenn <Prädikatausdruck > ist "true", wird das Ereignis verarbeitet, indem Sie die Aktionen und Zielen für die Sitzung.If <predicate_expression> is true, the event is processed further by the actions and targets for the session. Wenn <Prädikatausdruck > ist "false", der Ereignis von der Sitzung vor der Verarbeitung von den Aktionen und Zielen für die Sitzung gelöscht wird.If <predicate_expression> is false, the event is dropped by the session before being processed by the actions and targets for the session. Die Länge von Prädikatausdrücken ist auf 3000 Zeichen beschränkt, wodurch die Länge von Zeichenfolgenargumenten eingeschränkt wird.Predicate expressions are limited to 3000 characters, which limits string arguments.

    event_field_nameevent_field_name
    Ist der Name des Ereignisfelds, das die Prädikatquelle identifiziert.Is the name of the event field that identifies the predicate source.

    [Event_module_guid]. Event_package_name. predicate_source_name[event_module_guid].event_package_name.predicate_source_name
    Ist der Name der globalen Prädikatquelle, wobei Folgendes gilt:Is the name of the global predicate source where:

  • Event_module_guid ist die GUID für das Modul, das das Ereignis enthält.event_module_guid is the GUID for the module that contains the event.

  • Event_package_name ist das Paket, das das prädikatobjekt enthält.event_package_name is the package that contains the predicate object.

  • Predicate_source_name wird in der dm_xe_objects-Sicht als Object_type 'Pred_source' definiert.predicate_source_name is defined in the sys.dm_xe_objects view as object_type 'pred_source'.

    [Event_module_guid]. Event_package_name. predicate_compare_name[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:Is the name of the predicate object to associate with the event, where:

  • Event_module_guid ist die GUID für das Modul, das das Ereignis enthält.event_module_guid is the GUID for the module that contains the event.

  • Event_package_name ist das Paket, das das prädikatobjekt enthält.event_package_name is the package that contains the predicate object.

  • Predicate_compare_name ist eine globale Quelle, die in der dm_xe_objects-Sicht als Object_type 'Pred_compare' definiert.predicate_compare_name is a global source defined in the sys.dm_xe_objects view as object_type 'pred_compare'.

    numbernumber
    Alle numerischen Typen umfassen decimal.Is any numeric type including 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.Limitations are the lack of available physical memory or a number that is too large to be represented as a 64-bit integer.

    "Zeichenfolge"'string'
    Entweder eine ANSI- oder Unicode-Zeichenfolge, die vom Prädikatvergleich verlangt wird.Either an ANSI or Unicode string as required by the predicate compare. Für die Prädikatvergleichsfunktionen wird keine implizite Zeichenfolgentypkonvertierung ausgeführt.No implicit string type conversion is performed for the predicate compare functions. Die Übergabe des falschen Typs führt zu einem Fehler.Passing the wrong type results in an error.

    ADD TARGET [Event_module_guid]. Event_package_name. ZielnameADD TARGET [event_module_guid].event_package_name.target_name
    Ist das Ziel, das mit der Ereignissitzung zu verknüpfen ist. Dabei gilt:Is the target to associate with the event session, where:

  • Event_module_guid ist die GUID für das Modul, das das Ereignis enthält.event_module_guid is the GUID for the module that contains the event.

  • Event_package_name ist das Paket, das das Aktionsobjekt enthält.event_package_name is the package that contains the action object.

  • Target_name ist das Ziel.target_name is the target. Ziele werden in der sys.dm_xe_objects-Sicht als object_type 'target' angezeigt.Targets appear in sys.dm_xe_objects view as object_type 'target'.

    Legen Sie { Target_parameter_name= <Wert > [,... n] }SET { target_parameter_name= <value> [, ...n] }
    Legt einen Zielparameter fest.Sets a target parameter. Zielparameter werden in der dm_xe_object_columns-Sicht mit Column_type 'customizable' und Object_name = Target_name.Target parameters appear in the sys.dm_xe_object_columns view as column_type 'customizable' and object_name = target_name.

Wichtig

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.If you are using the ring buffer target, we recommend that you set the max_memory target parameter to 2048 kilobytes (KB) to help avoid possible data truncation of the XML output. Weitere Informationen zu die unterschiedlichen Zieltypen verwenden, finden Sie unter SQL Server Extended Events Targets.For more information about when to use the different target types, see SQL Server Extended Events Targets.

MIT ( <Ereignissitzungsoptionen > [,... n ]) Gibt Optionen an, mit der ereignissitzung zu verwenden.WITH ( <event_session_options> [ ,...n] ) Specifies options to use with the event session.

MAX_MEMORY =Größe [KB | MB ]MAX_MEMORY =size [ KB | MB ]
Gibt an, wieviel Arbeitsspeicher der Sitzung für die Ereignispufferung maximal zugeordnet werden soll.Specifies the maximum amount of memory to allocate to the session for event buffering. Der Standardwert ist 4 MB.The default is 4 MB. Größe ist eine ganze Zahl und Kilobyte (KB) oder Megabyte (MB) angegeben werden können.size is a whole number and can be a kilobyte (KB) or a megabyte (MB) value.

EVENT_RETENTION_MODE = { ALLOW_SINGLE_EVENT_LOSS | ALLOW_MULTIPLE_EVENT_LOSS | NO_EVENT_LOSS}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.Specifies the event retention mode to use for handling event loss.

ALLOW_SINGLE_EVENT_LOSSALLOW_SINGLE_EVENT_LOSS
Ein Ereignis der Sitzung darf verloren gehen.An event can be lost from the session. Ein einzelnes Ereignis wird nur gelöscht, wenn alle Ereignispuffer gefüllt sind.A single event is only dropped when all the event buffers are full. Wenn bei gefüllten Ereignispuffern nur ein Ereignis verloren geht, sind akzeptable SQL ServerSQL Server-Leistungsmerkmale möglich, während Datenverluste im verarbeiteten Ereignisdatenstrom minimiert werden.Losing a single event when event buffers are full allows for acceptable SQL ServerSQL Server performance characteristics, while minimizing the loss of data in the processed event stream.

ALLOW_MULTIPLE_EVENT_LOSSALLOW_MULTIPLE_EVENT_LOSS
Volle Ereignispuffer, die mehrere Ereignisse enthalten, dürfen in der Sitzung verloren gehen.Full event buffers containing multiple events can be lost from the session. Die Anzahl verloren gegangener Ereignisse ist hängt von der Größe des Speichers, der Partitionierung des Speichers und der Größe der Ereignisse im Puffer der Sitzung zugeordnetThe number of events lost is dependant upon the memory size allocated to the session, the partitioning of the memory, and the size of the events in the buffer. 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.This option minimizes performance impact on the server when event buffers are quickly filled, but large numbers of events can be lost from the session.

NO_EVENT_LOSSNO_EVENT_LOSS
Verluste von Ereignissen sind nicht zulässig.No event loss is allowed. Diese Option wird sichergestellt, dass alle ausgelösten Ereignisse beibehalten werden.This option ensures that all events raised will be retained. Diese Option verwendet wird, müssen alle Aufgaben, die Ereignisse auslösen, warten Sie, bis in einem Ereignispuffer Platz verfügbar wird.Using this option forces all tasks that fire events to wait until space is available in an event buffer. Dies kann spürbare Leistungsprobleme verursachen, während die Ereignissitzung aktiv ist.This may cause detectable performance issues while the event session is active. Möglicherweise werden Benutzerverbindungen blockiert, während auf das Leeren von Ereignissen aus dem Puffer gewartet wird.User connections may stall while waiting for events to be flushed from the buffer.

MAX_DISPATCH_LATENCY = { Sekunden Sekunden | UNENDLICHE }MAX_DISPATCH_LATENCY = { seconds SECONDS | INFINITE }
Gibt an, wie lange Ereignisse zwischengespeichert werden, bevor sie an Ereignissitzungsziele gesendet werden.Specifies the amount of time that events will be buffered in memory before being dispatched to event session targets. Standardmäßig ist dieser Wert auf 30 Sekunden festgelegt.By default, this value is set to 30 seconds.

Sekunden Sekundenseconds SECONDS
Die Wartezeit in Sekunden, bevor die Puffer geleert werden und ihr Inhalt an die Ziele gesendet wird.The time, in seconds, to wait before starting to flush buffers to targets. Sekunden ist eine ganze Zahl.seconds is a whole number. Der Latenzzeitwert muss mindestens 1 Sekunde betragen.The minimum latency value is 1 second. Mit dem Wert 0 kann jedoch eine INFINITE-Latenzzeit angegeben werden.However, 0 can be used to specify INFINITE latency.

UNBEGRENZTEINFINITE
Die Puffer werden nur dann geleert und ihr Inhalt an die Ziele gesendet, wenn die Puffer voll sind oder wenn die Ereignissitzung geschlossen wird.Flush buffers to targets only when the buffers are full, or when the event session closes.

Hinweis

MAX_DISPATCH_LATENCY = 0 SECONDS entspricht MAX_DISPATCH_LATENCY = INFINITE.MAX_DISPATCH_LATENCY = 0 SECONDS is equivalent to MAX_DISPATCH_LATENCY = INFINITE.

MAX_EVENT_SIZE =Größe [KB | MB ]MAX_EVENT_SIZE =size [ KB | MB ]
Gibt die maximal zulässige Größe für Ereignisse an.Specifies the maximum allowable size for events. 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.MAX_EVENT_SIZE should only be set to allow single events larger than MAX_MEMORY; setting it to less than MAX_MEMORY will raise an error. Größe ist eine ganze Zahl und Kilobyte (KB) oder Megabyte (MB) angegeben werden können.size is a whole number and can be a kilobyte (KB) or a megabyte (MB) value. Wenn Größe in Kilobyte angegeben wird, die zulässige Mindestgröße beträgt 64 KB.If size is specified in kilobytes, the minimum allowable size is 64 KB. Wenn MAX_EVENT_SIZE festgelegt ist, zwei Puffer der Größe werden zusätzlich zu MAX_MEMORY erstellt.When MAX_EVENT_SIZE is set, two buffers of size are created in addition to MAX_MEMORY. Dies bedeutet, dass der gesamte für die Ereignispufferung verwendete Arbeitsspeicher dem Wert von MAX_MEMORY + 2 * MAX_EVENT_SIZE entspricht.This means that the total memory used for event buffering is MAX_MEMORY + 2 * MAX_EVENT_SIZE.

MEMORY_PARTITION_MODE = { NONE | PER_NODE | PER_CPU}MEMORY_PARTITION_MODE = { NONE | PER_NODE | PER_CPU }
Gibt den Speicherort an, an dem Ereignispuffer erstellt werden.Specifies the location where event buffers are created.

NONENONE
Innerhalb der SQL ServerSQL Server-Instanz wird ein einzelner Satz von Puffern erstellt.A single set of buffers are created within the SQL ServerSQL Server instance.

PER_NODEPER_NODE
Ein Satz von Puffern wird für jeden NUMA-Knoten erstellt.A set of buffers are created for each NUMA node.

PER_CPUPER_CPU
Ein Satz von Puffern wird für jede CPU erstellt.A set of buffers are created for each CPU.

TRACK_CAUSALITY = {ON | OFF }TRACK_CAUSALITY = { ON | OFF }
Gibt an, ob Kausalität verfolgt wird.Specifies whether or not causality is tracked. Wenn das Verfolgen der Kausalität aktiviert ist, können ähnliche Ereignisse auf anderen Serververbindungen korreliert werden.If enabled, causality allows related events on different server connections to be correlated together.

STARTUP_STATE = {ON | OFF }STARTUP_STATE = { ON | OFF }
Gibt an, ob diese Ereignissitzung beim Start von SQL ServerSQL Server automatisch gestartet werden soll.Specifies whether or not to start this event session automatically when SQL ServerSQL Server starts.

Hinweis

Wenn STARTUP_STATE = ON, beginnt die Ereignissitzung erst, wenn SQL Server beendet und anschließend neu gestartet wird.If STARTUP_STATE = ON, the event session will only start if SQL Server is stopped and then restarted.

ONON
Die Ereignissitzung wird beim Start gestartet.The event session is started at startup.

OFFOFF
Die Ereignissitzung wird nicht beim Start gestartet.The event session is not started at startup.

HinweiseRemarks

Die Rangfolge der logischen Operatoren beginnt mit NOT (höchster Operator). Darauf folgt AND und anschließend OR.The order of precedence for the logical operators is NOT (highest), followed by AND, followed by OR.

BerechtigungenPermissions

Erfordert die ALTER ANY EVENT SESSION-Berechtigung.Requires the ALTER ANY EVENT SESSION permission.

BeispieleExamples

Das folgende Beispiel zeigt, wie eine Ereignissitzung mit der Bezeichnung test_session erstellt wird.The following example shows how to create an event session named test_session. In diesem Beispiel werden zwei Ereignisse hinzugefügt, und das Ziel 'Ereignisablaufverfolgung für Windows' wird verwendet.This example adds two events and uses the Event Tracing for Windows target.

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 auchSee Also

ALTER EVENT SESSION (Transact-SQL) ALTER EVENT SESSION (Transact-SQL)
DROP EVENT SESSION (Transact-SQL) DROP EVENT SESSION (Transact-SQL)
Sys. server_event_sessions ( Transact-SQL ) sys.server_event_sessions (Transact-SQL)
dm_xe_objects ( Transact-SQL ) sys.dm_xe_objects (Transact-SQL)
sys.dm_xe_object_columns (Transact-SQL)sys.dm_xe_object_columns (Transact-SQL)