SKAPA HÄNDELSESESSION (Transact-SQL)

Gäller för:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceSQL-databas i Förhandsversion av Microsoft Fabric

Skapar en extended events-session som identifierar de händelser som ska samlas in, målen för händelsesessionen och alternativen för händelsesessionen.

Transact-SQL syntaxkonventioner

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

Arguments

event_session_name

Det användardefinierade namnet på händelsesessionen. event_session_name är alfanumeriskt, kan vara upp till 128 tecken, måste vara unikt i en instans av SQL Server och måste följa reglerna för databasidentifierare.

PÅ { SERVER | DATABAS }

Avgör om händelsesessionen finns i kontexten för servern eller databasen.

Azure SQL Database och SQL Database i Microsoft Fabric Preview kräver DATABASE.

LÄGG TILL HÄNDELSE [event_module_guid]. event_package_name. event_name

Händelsen som ska associeras med händelsesessionen, där:

• event_module_guid är GUID för modulen som innehåller händelsen.
• event_package_name är paketet som innehåller händelsen.
• event_name är händelsenamnet.

Tillgängliga händelser kan hittas genom att köra följande fråga:

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 = <value> [ ,... n ] }

Anpassningsbara attribut för händelsen.

Anpassningsbara attribut för en viss händelse kan hittas genom att köra följande fråga:

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

Åtgärden som ska associeras med händelsen, där:

• event_module_guid är GUID för modulen som innehåller åtgärden.
• event_package_name är paketet som innehåller åtgärden.
• action_name är namnet på åtgärden.

Tillgängliga åtgärder kan hittas genom att köra följande fråga:

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>

Anger predikatuttrycket som används för att avgöra om en händelse ska bearbetas. Om <predicate_expression> är sant bearbetas händelsen ytterligare av åtgärderna och målen för sessionen. Om <predicate_expression> är falskt tas händelsen bort och ytterligare åtgärd och målbearbetning undviks. Varje predikatuttryck är begränsat till 3 000 tecken.

event_field_name

Namnet på det händelsefält som identifierar predikatkällan.

Fälten för en händelse kan hittas genom att köra följande fråga:

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

Namnet på den globala predikatkällan där:

• event_module_guid är GUID för modulen som innehåller händelsen.
• event_package_name är paketet som innehåller predikatkällans objekt.
• predicate_source_name är namnet på predikatkällan.

Predikatkällor kan hittas genom att köra följande fråga:

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

Namnet på predikatets jämförelseobjekt, där:

• event_module_guid är GUID för modulen som innehåller händelsen.
• event_package_name är paketet som innehåller jämförelseobjektet för predikat.
• predicate_compare_name är predikatjäxets jämförelsenamn.

Predikatjänare kan hittas genom att köra följande fråga:

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

Alla numeriska typer som kan representeras som ett 64-bitars heltal.

"sträng"

Antingen en ANSI- eller Unicode-sträng som krävs av predikatjäxatorn. Ingen implicit strängtypkonvertering utförs för jämförelsefunktionerna för predikat. Om värdet för en oväntad typ skickas resulterar det i ett fel.

LÄGG TILL MÅL [event_module_guid]. event_package_name. target_name

Är målet att associera med händelsesessionen, där:

• event_module_guid är GUID för modulen som innehåller målet.
• event_package_name är paketet som innehåller målet.
• target_name är målnamnet.

Tillgängliga mål kan hittas genom att köra följande fråga:

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;

En händelsesession kan ha noll, ett eller flera mål. Alla mål som läggs till i en händelsesession måste vara olika. Du kan till exempel inte lägga till ett andra event_file mål i en session som redan har ett event_file mål.

Mer information, inklusive användningsexempel för vanliga mål, finns i Extended Events-mål.

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

Anger en målparameter.

Om du vill se alla målparametrar och deras beskrivningar kör du följande fråga och ersätter target-name-placeholder med målnamnet, till exempel event_file, ring_buffer, histogramosv.:

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

Mer information om måltyper finns i Extended Events-mål.

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

Anger vilka alternativ som ska användas med händelsesessionen.

MAX_MEMORY = storlek [ KB | MB ]

Anger den maximala mängden minne som ska allokeras till sessionen för händelsebuffertning. Standardvärdet är 4 MB. storleken är ett heltal och kan vara ett kilobyte (KB) eller ett MB-värde. Det maximala beloppet får inte överstiga 2 GB (2 048 MB). Det rekommenderas dock inte att du använder minnesvärden i GB-intervallet.

EVENT_RETENTION_MODE = { ALLOW_SINGLE_EVENT_LOSS | ALLOW_MULTIPLE_EVENT_LOSS | NO_EVENT_LOSS }

Anger det händelsekvarhållningsläge som ska användas för hantering av händelseförlust.

• ALLOW_SINGLE_EVENT_LOSS

  En händelse kan gå förlorad från sessionen. En enskild händelse tas bara bort när alla händelsebuffertar är fulla. Om du förlorar en enskild händelse när händelsebuffertar är fulla minimeras prestandapåverkan samtidigt som dataförlusten i den bearbetade händelseströmmen minimeras.

• ALLOW_MULTIPLE_EVENT_LOSS

  Fullständiga händelsebuffertar som innehåller flera händelser kan gå förlorade från sessionen. Antalet förlorade händelser beror på den minnesstorlek som allokerats till sessionen, partitioneringen av minnet och storleken på händelserna i bufferten. Det här alternativet undviker vanligtvis prestandapåverkan på servern när händelsebuffertar fylls snabbt, men ett stort antal händelser kan gå förlorade från sessionen.

• NO_EVENT_LOSS

  Ingen händelseförlust tillåts. Det här alternativet säkerställer att alla händelser som genereras behålls. Med det här alternativet tvingar du alla uppgifter som utlöser händelser att vänta tills utrymme är tillgängligt i en händelsebuffert. Om du använder NO_EVENT_LOSS kan det orsaka identifieringsbara prestandaproblem när händelsesessionen är aktiv. Användarsessioner och frågor kan stoppas i väntan på att händelser ska rensas från bufferten.

  Anmärkning

  För händelsefilens mål i Azure SQL Database, SQL Database i Microsoft Fabric Preview och Azure SQL Managed Instance (med SQL Server 2025 eller Always-up-to-dateupdate policy) fungerar från och med juni 2024 NO_EVENT_LOSS samma som ALLOW_SINGLE_EVENT_LOSS. Om du anger NO_EVENT_LOSSreturneras en varning med meddelande-ID 25665, allvarlighetsgrad 10 och meddelandet This target doesn't support the NO_EVENT_LOSS event retention mode. The ALLOW_SINGLE_EVENT_LOSS retention mode is used instead. och sessionen skapas.

  Den här ändringen undviker tidsgränser för anslutningar, redundansfördröjningar och andra problem som kan minska databastillgängligheten när NO_EVENT_LOSS den används med händelsefilmål i Azure Blob Storage.

  NO_EVENT_LOSS planeras att tas bort som ett argument som stöds EVENT_RETENTION_MODE i framtida uppdateringar av Azure SQL Database, SQL Database i Microsoft Fabric Preview och Azure SQL Managed Instance. Undvik att använda den här funktionen i nytt utvecklingsarbete och planera att ändra program som för närvarande använder den här funktionen.

MAX_DISPATCH_LATENCY = { sekunder | INFINITE }

Anger hur lång tid händelser buffrar i minnet innan de skickas till händelsesessionsmål. Som standard är det här värdet inställt på 30 sekunder.

• SekunderSECONDS

  Tiden, i sekunder, att vänta innan du börjar spola buffertar till mål. sekunder är ett heltal. Minsta svarstidsvärde är 1 sekund. 0 kan dock användas för att ange OÄNDLIG svarstid.

• OÄNDLIG

  Töm buffertar till mål endast när buffertarna är fulla eller när händelsesessionen stängs.

MAX_EVENT_SIZE = storlek [ KB | MB ]

Anger den maximala tillåtna storleken för händelser. MAX_EVENT_SIZE bör endast anges för att tillåta enskilda händelser som är större än MAX_MEMORY. om du ställer in den på mindre än MAX_MEMORY uppstår ett fel. storleken är ett heltal och kan vara ett kilobyte (KB) eller ett MB-värde. Om storleken anges i kilobyte är den minsta tillåtna storleken 64 kB. När MAX_EVENT_SIZE har angetts skapas två buffertar av storlek utöver MAX_MEMORY, och det totala minnet som används för händelsebuffertning är MAX_MEMORY + 2 * MAX_EVENT_SIZE.

MEMORY_PARTITION_MODE = { NONE | PER_NODE | PER_CPU }

Anger tillhörigheten för händelsebuffertar. Andra alternativ än NONE resulterar i fler buffertar och högre minnesförbrukning, men kan undvika konkurrens och förbättra prestanda på större datorer.

• INGEN

  En enda uppsättning buffertar skapas i database engine-instansen.

• PER_NODE

  En uppsättning buffertar skapas för varje NUMA-nod.

• PER_CPU

  En uppsättning buffertar skapas för varje PROCESSOR.

TRACK_CAUSALITY = { ON | AV }

Anger om orsakssamband spåras eller inte. Om detta är aktiverat kan relaterade händelser på olika serveranslutningar korreleras tillsammans.

STARTUP_STATE = { ON | AV }

Anger om den här händelsesessionen ska startas automatiskt när SQL Server startas eller inte.

• ON

  Händelsesessionen startas vid start.

• OFF

  Händelsesessionen startas inte vid start.

MAX_DURATION = { tidsvaraktighet { SEKUNDER | MINUTER | TIMMAR | DAYS } | OBEGRÄNSAT }

Gäller för: FÖRHANDSVERSION AV SQL Server 2025 (17.x)

• OBEGRÄNSAD

  Skapar en händelsesession som körs på obestämd tid när den har startats tills den har stoppats med instruktionen ALTER EVENT SESSION ... STATE = STOP . Detta är standardvärdet om MAX_DURATION inte har angetts.

• tidsvaraktighet SEKUNDER | MINUTER | TIMMAR | DAGAR

  Skapar en händelsesession som stoppas automatiskt efter den angivna tiden som förflutit efter sessionens start. Den maximala varaktigheten som stöds är 2 147 483 sekunder eller 35 792 minuter, 596 timmar eller 24 dagar.

Mer information finns i Tidsbundna händelsesessioner.

Anmärkningar

Mer information om argument för händelsesessioner finns i Sessioner för utökade händelser.

Prioritetsordningen för de logiska operatorerna är NOT (högsta), följt av AND, följt av OR.

Permissions

SQL Server och Azure SQL Managed Instance kräver CREATE ANY EVENT SESSION (introducerades i SQL Server 2022) eller ALTER ANY EVENT SESSION behörighet.

Azure SQL Database och SQL Database i Microsoft Fabric Preview kräver behörigheten CREATE ANY DATABASE EVENT SESSION i databasen.

Examples

A. Exempel på SQL Server och Azure SQL Managed Instance

I följande exempel visas hur du skapar en händelsesession med namnet test_session. Det här exemplet lägger till två händelser och använder event_file målet, vilket begränsar storleken på varje fil till 256 MB och begränsar det behållna antalet filer till 10.

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. Azure SQL Database-exempel

Exempel på genomgångar finns i Skapa en händelsesession med ett event_file mål i Azure Storage och Skapa en händelsesession med ett ring_buffer mål i minnet.

Kodexemplen kan skilja sig åt för Azure SQL Database och SQL Managed Instance

Vissa Transact-SQL kodexempel som skrivits för SQL Server behöver små ändringar för att köras i Azure SQL Database eller SQL Database i Fabric. En kategori av sådana kodexempel omfattar katalogvyer vars namnprefix skiljer sig beroende på databasmotortypen:

• server_ - prefix för SQL Server och Azure SQL Managed Instance
• database_ - prefix för Azure SQL Database, SQL Database i Fabric och SQL Managed Instance

Azure SQL Database och SQL Database i Fabric stöder endast databasomfattande händelsesessioner. SQL Server Management Studio (SSMS) stöder databasomfattande händelsesessioner för Azure SQL Database: en nod för utökade händelser som innehåller databasomfattande sessioner visas under varje databas i Object Explorer.

Azure SQL Managed Instance stöder både databasomfattande sessioner och sessioner med serveromfattning. SSMS stöder fullständigt serveromfattande sessioner för SQL Managed Instance: en nod för utökade händelser som innehåller alla serveromfattande sessioner visas under mappen Hantering för varje hanterad instans i Object Explorer.

Som illustration listar och jämför följande tabell två delmängder av katalogvyer. Underuppsättningarna har olika namnprefix eftersom de stöder olika databasmotortyper.

Relaterat innehåll

• Skapa en händelsesession med ett event_file mål i Azure Storage
• Extended Events-mål
• sys.server_event_sessions (Transact-SQL)
• sys.dm_xe_objects (Transact-SQL)
• sys.dm_xe_object_columns (Transact-SQL)
• ALTER EVENT SESSION (Transact-SQL)
• TA BORT HÄNDELSESESSION (Transact-SQL)