ALTER EVENT SESSION (Transact-SQL)

Van toepassing op:SQL ServerAzure SQL Managed Instance

Start of stopt een gebeurtenissessie of wijzigt de configuratie van een gebeurtenissessie.

Transact-SQL syntaxis-conventies

Syntaxis

ALTER EVENT SESSION event_session_name
ON { SERVER | DATABASE }
{
    [ [ {  <add_drop_event> [ , ...n ] }
       | { <add_drop_event_target> [ , ...n ] } ]
    [ WITH ( <event_session_options> [ , ...n ] ) ]
    ]
    | [ STATE = { START | STOP } ]
}

<add_drop_event>::=
{
    [ ADD EVENT <event_specifier>
         [ ( {
                 [ SET { event_customizable_attribute = <value> [ , ...n ] } ]
                 [ ACTION ( { [event_module_guid].event_package_name.action_name [ , ...n ] } ) ]
                 [ WHERE <predicate_expression> ]
        } ) ]
   ]
   | DROP EVENT <event_specifier> }

<event_specifier> ::=
{
[event_module_guid].event_package_name.event_name
}
<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'
}

<add_drop_event_target>::=
{
    ADD TARGET <event_target_specifier>
        [ ( SET { target_parameter_name = <value> [ , ...n ] } ) ]
    | DROP TARGET <event_target_specifier>
}

<event_target_specifier>::=
{
    [event_module_guid].event_package_name.target_name
}

<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 naam van een bestaande gebeurtenissessie.

STATE = START | STOPPEN

Start of stopt de gebeurtenissessie. Het STATE argument moet zelfstandig worden opgegeven. Deze kan niet worden gecombineerd met andere argumenten in dezelfde ALTER EVENT SESSION instructie.

GEBEURTENIS <TOEVOEGEN event_specifier>

Identificeert een gebeurtenis die moet worden gekoppeld aan de gebeurtenissessie. < > event_specifier heeft de vorm van [event_module_guid].event_package_name. event_name, 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.

DROP EVENT <event_specifier>

Identificeert een gebeurtenis die moet worden verwijderd uit de gebeurtenissessie. Gebeurtenisaanduiding heeft de vorm van [event_module_guid]. event_package_name. event_name, waarbij:

• event_module_guid is de GUID voor de module die de gebeurtenis bevat.

• event_package_name is het pakket dat het actieobject bevat.

• event_name is het gebeurtenisobject.

  < > event_specifier moet een gebeurtenis identificeren die eerder aan de gebeurtenissessie is toegevoegd.

DOEL-event_target_specifier <TOEVOEGEN>

Identificeert een doel dat moet worden gekoppeld aan een gebeurtenissessie. De aanduiding voor het doel van de gebeurtenis heeft de vorm van [event_module_guid]. event_package_name. target_name, waarbij:

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

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_file, ring_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.

DROP TARGET <event_target_specifier>

Identificeert een doel dat moet worden verwijderd uit een gebeurtenissessie. De aanduiding voor het doel van de gebeurtenis heeft de vorm van [event_module_guid]. event_package_name. target_name, waarbij:

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

De doelaanduiding van de gebeurtenis moet een doel identificeren dat eerder aan de gebeurtenissessie is toegevoegd.

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 gebeurtenisstroom 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 en in 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 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.

• Seconden SECONDEN

  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 van gebeurtenissen 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 de database-engine 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

  Zorgt ervoor dat een gebeurtenissessie voor onbepaalde tijd wordt uitgevoerd zodra deze is gestart, totdat de ALTER EVENT SESSION ... STATE = STOP instructie is gestopt.

• tijdsduur SECONDEN | MINUTEN | UREN | DAGEN

  Zorgt ervoor dat een gebeurtenissessie 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 ADD en DROP argumenten kunnen niet worden gebruikt in dezelfde instructie.

Permissions

VOOR SQL Server en Azure SQL Managed Instance is de ALTER ANY EVENT SESSION machtiging vereist.

Voor Azure SQL Database is de ALTER ANY DATABASE EVENT SESSION machtiging in de database vereist.

Voorbeelden

Eén. Een gebeurtenissessie starten en stoppen

Als u dit voorbeeld wilt gebruiken met database-gebeurtenissessies, vervangt u door ON SERVERON DATABASE.

ALTER EVENT SESSION test_session ON SERVER STATE = START;
ALTER EVENT SESSION test_session ON SERVER STATE = STOP;

B. Nieuwe gebeurtenissen toevoegen aan een bestaande sessie

Als u dit voorbeeld wilt gebruiken met database-gebeurtenissessies, vervangt u door ON SERVERON DATABASE.

ALTER EVENT SESSION test_session ON SERVER
ADD EVENT sqlserver.database_transaction_begin,
ADD EVENT sqlserver.database_transaction_end;

C. Sessiestatistieken weergeven

Als u dit voorbeeld wilt gebruiken met database-gebeurtenissessies, vervangt u door sys.dm_xe_sessionssys.dm_xe_database_sessionsen sys.dm_xe_session_events door sys.dm_xe_database_session_events.

SELECT *
FROM sys.dm_xe_sessions
WHERE name = 'test_session';

SELECT se.*
FROM sys.dm_xe_session_events AS se
WHERE EXISTS (SELECT 1
              FROM sys.dm_xe_sessions AS s
              WHERE s.address = se.event_session_address
                    AND s.name = 'test_session');

Verwante inhoud

• GEBEURTENISSESSIE MAKEN (Transact-SQL)
• DROP EVENT SESSION (Transact-SQL)
• Uitgebreide SQL Server-gebeurtenissendoelen
• sys.server_event_sessions (Transact-SQL)
• sys.dm_xe_objects (Transact-SQL)
• sys.dm_xe_object_columns (Transact-SQL)