GEBEURTENISSESSIE MAKEN (Transact-SQL)

Van toepassing op:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceSQL-database in Microsoft Fabric Preview

Hiermee maakt u een uitgebreide gebeurtenissessie die de gebeurtenissen identificeert die moeten worden verzameld, de doelen van de gebeurtenissessie en de opties voor de gebeurtenissessie.

Transact-SQL syntaxis-conventies

Syntaxis

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

De door de gebruiker gedefinieerde naam voor de gebeurtenissessie. event_session_name alfanumeriek is, kan maximaal 128 tekens zijn, moet uniek zijn binnen een exemplaar van SQL Server en moet voldoen aan de regels voor database-id's.

OP { SERVER | DATABASE }

Bepaalt of de gebeurtenissessie zich in de context van de server of database bevindt.

Azure SQL Database en SQL-database in Microsoft Fabric Preview vereisen DATABASE.

GEBEURTENIS TOEVOEGEN [event_module_guid]. event_package_name. event_name

De gebeurtenis die moet worden gekoppeld aan de gebeurtenissessie, waarbij:

• event_module_guid is de GUID voor de module die de gebeurtenis bevat.
• event_package_name is het pakket dat de gebeurtenis bevat.
• event_name is de naam van de gebeurtenis.

Beschikbare gebeurtenissen vindt u door de volgende query uit te voeren:

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

Aanpasbare kenmerken voor de gebeurtenis.

Aanpasbare kenmerken voor een bepaalde gebeurtenis vindt u door de volgende query uit te voeren:

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;

ACTIE ( { [event_module_guid].event_package_name. action_name [ ,... n ] })

De actie die moet worden gekoppeld aan de gebeurtenis, waarbij:

• event_module_guid is de GUID voor de module die de actie bevat.
• event_package_name is het pakket dat de actie bevat.
• action_name is de naam van de actie.

Beschikbare acties vindt u door de volgende query uit te voeren:

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>

Hiermee geeft u de predicaatexpressie op die wordt gebruikt om te bepalen of een gebeurtenis moet worden verwerkt. Als <predicate_expression> waar is, wordt de gebeurtenis verder verwerkt door de acties en doelen voor de sessie. Als <predicate_expression> onwaar is, wordt de gebeurtenis verwijderd en wordt extra actie en doelverwerking voorkomen. Elke predicaatexpressie is beperkt tot 3000 tekens.

event_field_name

De naam van het gebeurtenisveld dat de predicaatbron identificeert.

De velden voor een gebeurtenis zijn te vinden door de volgende query uit te voeren:

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

De naam van de globale predicaatbron waarbij:

• event_module_guid is de GUID voor de module die de gebeurtenis bevat.
• event_package_name is het pakket dat het predicaatbronobject bevat.
• predicate_source_name is de naam van de predicaatbron.

Predicaatbronnen zijn te vinden door de volgende query uit te voeren:

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

De naam van het predicaat comparator-object, waarbij:

• event_module_guid is de GUID voor de module die de gebeurtenis bevat.
• event_package_name is het pakket dat het predicaat comparator-object bevat.
• predicate_compare_name is de predicaatvergelijkingsnaam.

Predicate comparators zijn te vinden door de volgende query uit te voeren:

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

Elk numeriek type dat kan worden weergegeven als een 64-bits geheel getal.

'tekenreeks'

Een ANSI- of Unicode-tekenreeks zoals vereist door de predicaatvergelijker. Er wordt geen impliciete conversie van tekenreekstypen uitgevoerd voor de functies voor predicaatvergelijking. Het doorgeven van de waarde van een onverwacht type resulteert in een fout.

ADD TARGET [event_module_guid]. event_package_name. target_name

Is het doel om te koppelen aan de gebeurtenissessie, waarbij:

• event_module_guid is de GUID voor de module die het doel bevat.
• event_package_name is het pakket dat het doel bevat.
• target_name is de doelnaam.

Beschikbare doelen zijn te vinden door de volgende query uit te voeren:

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;

Een gebeurtenissessie kan nul, één of veel doelen hebben. Alle doelen die zijn toegevoegd aan een gebeurtenissessie, moeten verschillen. U kunt bijvoorbeeld geen tweede event_file doel toevoegen aan een sessie die al een event_file doel heeft.

Zie Uitgebreide gebeurtenissendoelen voor meer informatie, waaronder gebruiksvoorbeelden voor veelgebruikte doelen.

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

Hiermee stelt u een doelparameter in.

Als u alle doelparameters en de bijbehorende beschrijvingen wilt zien, voert u de volgende query uit, waarbij u target-name-placeholder vervangt door de doelnaam, zoals event_filering_buffer, histogram, , enzovoort:

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

Zie Uitgebreide gebeurtenissendoelen voor meer informatie over doeltypen.

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

Hiermee geeft u de opties voor gebruik met de gebeurtenissessie.

MAX_MEMORY = grootte [ kB | MB ]

Hiermee geeft u de maximale hoeveelheid geheugen die moet worden toegewezen aan de sessie voor gebeurtenisbuffering. De standaardwaarde is 4 MB. grootte is een geheel getal en kan een kilobyte (KB) of een megabytewaarde (MB) zijn. Het maximumbedrag mag niet groter zijn dan 2 GB (2048 MB). Het gebruik van geheugenwaarden in gb-bereik wordt echter niet aanbevolen.

EVENT_RETENTION_MODE = { ALLOW_SINGLE_EVENT_LOSS | ALLOW_MULTIPLE_EVENT_LOSS | NO_EVENT_LOSS }

Hiermee geeft u de retentiemodus voor gebeurtenissen op die moet worden gebruikt voor het afhandelen van gebeurtenisverlies.

• ALLOW_SINGLE_EVENT_LOSS

  Een gebeurtenis kan verloren gaan vanuit de sessie. Eén gebeurtenis wordt alleen verwijderd wanneer alle gebeurtenisbuffers vol zijn. Als u één gebeurtenis kwijtraakt wanneer gebeurtenisbuffers volledig zijn, wordt de impact op de prestaties geminimaliseerd, terwijl ook het verlies van gegevens in de verwerkte eventstream wordt geminimaliseerd.

• ALLOW_MULTIPLE_EVENT_LOSS

  Volledige gebeurtenisbuffers met meerdere gebeurtenissen kunnen verloren gaan vanuit de sessie. Het aantal verloren gebeurtenissen is afhankelijk van de geheugengrootte die is toegewezen aan de sessie, de partitionering van het geheugen en de grootte van de gebeurtenissen in de buffer. Deze optie voorkomt over het algemeen dat de prestaties van de server worden beïnvloed wanneer gebeurtenisbuffers snel worden gevuld, maar grote aantallen gebeurtenissen kunnen verloren gaan uit de sessie.

• NO_EVENT_LOSS

  Er is geen gebeurtenisverlies toegestaan. Deze optie zorgt ervoor dat alle gegenereerde gebeurtenissen worden bewaard. Als u deze optie gebruikt, worden alle taken die gebeurtenissen activeren gedwongen te wachten totdat er ruimte beschikbaar is in een gebeurtenisbuffer. Het gebruik van NO_EVENT_LOSS kan detecteerbare prestatieproblemen veroorzaken terwijl de gebeurtenissessie actief is. Gebruikerssessies en query's kunnen vastlopen terwijl wordt gewacht tot gebeurtenissen uit de buffer worden leeggemaakt.

  Opmerking

  Voor de doelen van het gebeurtenisbestand in Azure SQL Database, SQL-database in Microsoft Fabric Preview en Azure SQL Managed Instance (met sql Server 2025 of Always-up-to-dateupdate policy), vanaf juni 2024, NO_EVENT_LOSS gedraagt zich hetzelfde als ALLOW_SINGLE_EVENT_LOSS. Als u opgeeft NO_EVENT_LOSS, wordt er een waarschuwing met bericht-id 25665, ernst 10 en het bericht This target doesn't support the NO_EVENT_LOSS event retention mode. The ALLOW_SINGLE_EVENT_LOSS retention mode is used instead. geretourneerd en wordt de sessie gemaakt.

  Deze wijziging voorkomt verbindingstime-outs, failoververtragingen en andere problemen die de beschikbaarheid van databases kunnen verminderen wanneer NO_EVENT_LOSS deze worden gebruikt met gebeurtenisbestandsdoelen in Azure Blob Storage.

  NO_EVENT_LOSS is gepland voor verwijdering als een ondersteund EVENT_RETENTION_MODE argument in toekomstige updates voor Azure SQL Database, SQL-database in Microsoft Fabric Preview en Azure SQL Managed Instance. Vermijd het gebruik van deze functie in nieuwe ontwikkelwerkzaamheden en plan om toepassingen te wijzigen die momenteel gebruikmaken van deze functie.

MAX_DISPATCH_LATENCY = { seconden | ONEINDIG }

Hiermee geeft u de hoeveelheid tijd op die gebeurtenissen in het geheugen worden gebufferd voordat ze worden verzonden naar gebeurtenissessiedoelen. Deze waarde is standaard ingesteld op 30 seconden.

• SecondenSECONDS

  De tijd, in seconden, om te wachten voordat u begint met het leegmaken van buffers naar doelen. seconden is een geheel getal. De minimumlatentiewaarde is 1 seconde. 0 kan echter worden gebruikt om ONEINDIGE latentie op te geven.

• ONEINDIG

  Spoel buffers alleen naar doelen wanneer de buffers vol zijn of wanneer de gebeurtenissessie wordt gesloten.

MAX_EVENT_SIZE = grootte [ KB | MB ]

Hiermee geeft u de maximaal toegestane grootte voor gebeurtenissen. MAX_EVENT_SIZE mag alleen worden ingesteld om afzonderlijke gebeurtenissen toe te staan die groter zijn dan MAX_MEMORY; als u deze instelt op minder dan MAX_MEMORY wordt er een fout gegenereerd. grootte is een geheel getal en kan een kilobyte (KB) of een megabytewaarde (MB) zijn. Als de grootte is opgegeven in kilobytes, is de minimale toegestane grootte 64 kB. Wanneer MAX_EVENT_SIZE is ingesteld , worden er naast MAX_MEMORY twee buffers gemaakt en wordt het totale geheugen dat wordt gebruikt voor gebeurtenisbuffering MAX_MEMORY + 2 * MAX_EVENT_SIZE.

MEMORY_PARTITION_MODE = { NONE | PER_NODE | PER_CPU }

Hiermee geeft u de affiniteit van gebeurtenisbuffers. Andere opties dan NONE resulteren in meer buffers en een hoger geheugenverbruik, maar kunnen conflicten voorkomen en de prestaties op grotere machines verbeteren.

• GEEN

  Er wordt één set buffers gemaakt in het database-engine-exemplaar.

• PER_NODE

  Er wordt een set buffers gemaakt voor elk NUMA-knooppunt.

• PER_CPU

  Er wordt een set buffers gemaakt voor elke CPU.

TRACK_CAUSALITY = { AAN | UIT }

Hiermee geeft u op of causaliteit al dan niet wordt bijgehouden. Als deze optie is ingeschakeld, kunnen gerelateerde gebeurtenissen op verschillende serververbindingen aan elkaar worden gecorreleerd.

STARTUP_STATE = { ON | UIT }

Hiermee geeft u op of deze gebeurtenissessie automatisch moet worden gestart wanneer SQL Server wordt gestart.

• AAN

  De gebeurtenissessie wordt gestart bij het opstarten.

• OFF

  De gebeurtenissessie wordt niet gestart bij het opstarten.

MAX_DURATION = { tijdsduur { SECONDEN | MINUTEN | UREN | DAYS } | ONBEPERKT }

Van toepassing op: SQL Server 2025 (17.x) Preview

• ONBEGRENSD

  Hiermee maakt u een gebeurtenissessie die voor onbepaalde tijd wordt uitgevoerd nadat deze is gestart, totdat de ALTER EVENT SESSION ... STATE = STOP instructie is gestopt. Dit is de standaardinstelling als MAX_DURATION deze niet is opgegeven.

• tijdsduur SECONDEN | MINUTEN | UREN | DAGEN

  Hiermee maakt u een gebeurtenissessie die automatisch stopt nadat de opgegeven tijd is verstreken nadat de sessie is gestart. De maximale ondersteunde duur is 2.147.483 seconden of 35.792 minuten, of 596 uur of 24 dagen.

Zie Tijdgebonden gebeurtenissessies voor meer informatie.

Opmerkingen

Zie Uitgebreide gebeurtenissensessies voor meer informatie over argumenten voor gebeurtenissessies.

De volgorde van prioriteit voor de logische operators is NOT (hoogste), gevolgd door AND, gevolgd door OR.

Permissions

SQL Server en Azure SQL Managed Instance vereisen de CREATE ANY EVENT SESSION (geïntroduceerd in SQL Server 2022) of ALTER ANY EVENT SESSION de machtiging.

Voor Azure SQL Database en SQL-database in Microsoft Fabric Preview is de CREATE ANY DATABASE EVENT SESSION machtiging in de database vereist.

Voorbeelden

Eén. Voorbeeld van SQL Server en Azure SQL Managed Instance

In het volgende voorbeeld ziet u hoe u een gebeurtenissessie met de naam test_sessionmaakt. In dit voorbeeld worden twee gebeurtenissen toegevoegd en wordt het event_file doel gebruikt, waardoor de grootte van elk bestand wordt beperkt tot 256 MB en het bewaarde aantal bestanden wordt beperkt tot 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. Voorbeelden van Azure SQL Database

Bekijk bijvoorbeeld Een gebeurtenissessie maken met een event_file doel in Azure Storage en maak een gebeurtenissessie met een ring_buffer doel in het geheugen.

Codevoorbeelden kunnen verschillen voor Azure SQL Database en SQL Managed Instance

Sommige Transact-SQL codevoorbeelden die zijn geschreven voor SQL Server, hebben kleine wijzigingen nodig om te worden uitgevoerd in Azure SQL Database of SQL Database in Fabric. Een categorie van dergelijke codevoorbeelden omvat catalogusweergaven waarvan de naamvoorvoegsels verschillen, afhankelijk van het type database-engine:

• server_ - voorvoegsel voor SQL Server en Azure SQL Managed Instance
• database_ - voorvoegsel voor Azure SQL Database, SQL Database in Fabric en SQL Managed Instance

Azure SQL Database en SQL Database in Fabric ondersteunen alleen gebeurtenissessies met databasebereik. SQL Server Management Studio (SSMS) ondersteunt gebeurtenissessies met databasebereik voor Azure SQL Database: een knooppunt uitgebreide gebeurtenissen met sessies met databasebereik wordt weergegeven onder elke database in Objectverkenner.

Azure SQL Managed Instance ondersteunt zowel sessies met databasebereik als sessies met serverbereik. SSMS biedt volledige ondersteuning voor sessies met serverbereik voor SQL Managed Instance: een knooppunt uitgebreide gebeurtenissen met alle sessies met serverbereik wordt weergegeven onder de beheermap voor elk beheerd exemplaar in Objectverkenner.

Ter illustratie worden in de volgende tabel twee subsets van catalogusweergaven weergegeven en vergeleken. De subsets hebben verschillende naamvoorvoegsels omdat ze verschillende typen database-engine ondersteunen.

Verwante inhoud

• Een gebeurtenissessie maken met een event_file-doel in Azure Storage
• Uitgebreide gebeurtenissendoelen
• sys.server_event_sessions (Transact-SQL)
• sys.dm_xe_objects (Transact-SQL)
• sys.dm_xe_object_columns (Transact-SQL)
• ALTER EVENT SESSION (Transact-SQL)
• DROP EVENT SESSION (Transact-SQL)