ALTER EVENT SESSION (Transact-SQL)

gäller för:SQL ServerAzure SQL Managed Instance

Startar eller stoppar en händelsesession eller ändrar en händelsesessionskonfiguration.

Transact-SQL syntaxkonventioner

Syntax

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

Namnet på en befintlig händelsesession.

STATE = START | STANNA

Startar eller stoppar händelsesessionen. Argumentet STATE måste anges på egen hand. Det kan inte kombineras med andra argument i samma ALTER EVENT SESSION -instruktion.

LÄGG TILL HÄNDELSE <event_specifier>

Identifierar en händelse som ska associeras med händelsesessionen. < > event_specifier är i form av [event_module_guid].event_package_name. event_name, 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 namnet på händelsen.

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.

SLÄPP HÄNDELSE <event_specifier>

Identifierar en händelse som ska tas bort från händelsesessionen. Händelsespecificeraren är i form av [event_module_guid]. event_package_name. event_name, där:

• event_module_guid är GUID för modulen som innehåller händelsen.

• event_package_name är paketet som innehåller åtgärdsobjektet.

• event_name är händelseobjektet.

  < > event_specifier måste identifiera en händelse som tidigare lades till i händelsesessionen.

LÄGG TILL MÅL <event_target_specifier>

Identifierar ett mål som ska associeras med en händelsesession. Händelsemålsspecificeraren är i form av [event_module_guid]. event_package_name. target_name, där:

• event_module_guid är GUID för modulen som innehåller händelsen.
• event_package_name är paketet som innehåller åtgärdsobjektet.
• target_name är målets namn.

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.

SLÄPP MÅL <event_target_specifier>

Identifierar ett mål att ta bort från en händelsesession. Händelsemålsspecificeraren är i form av [event_module_guid]. event_package_name. target_name, där:

• event_module_guid är GUID för modulen som innehåller händelsen.
• event_package_name är paketet som innehåller åtgärdsobjektet.
• target_name är målets namn.

Händelsemålsspecificeraren måste identifiera ett mål som tidigare lades till i händelsesessionen.

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 och i 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 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.

• Sekunder SEKUNDER

  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 händelsesamband 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 databasmotorn 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

  Gör att en händelsesession körs på obestämd tid när den har startats tills den har slutat använda -instruktionen ALTER EVENT SESSION ... STATE = STOP .

• tidsvaraktighet SEKUNDER | MINUTER | TIMMAR | DAGAR

  Gör att en händelsesession stoppas automatiskt efter att den angivna tiden 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.

Argumenten ADD och DROP kan inte användas i samma -instruktion.

Permissions

SQL Server och Azure SQL Managed Instance kräver behörigheten ALTER ANY EVENT SESSION .

Azure SQL Database kräver behörigheten ALTER ANY DATABASE EVENT SESSION i databasen.

Examples

A. Starta och stoppa en händelsesession

Om du vill använda det här exemplet med databashändelsesessioner ersätter du ON SERVER med ON DATABASE.

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

B. Lägga till nya händelser i en befintlig session

Om du vill använda det här exemplet med databashändelsesessioner ersätter du ON SERVER med ON DATABASE.

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

C. Visa sessionsstatistik

Om du vill använda det här exemplet med databashändelsesessioner ersätter du sys.dm_xe_sessions med sys.dm_xe_database_sessionsoch sys.dm_xe_session_events med 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');

Relaterat innehåll

• SKAPA HÄNDELSESESSION (Transact-SQL)
• TA BORT HÄNDELSESESSION (Transact-SQL)
• Sql Server Extended Events-mål
• sys.server_event_sessions (Transact-SQL)
• sys.dm_xe_objects (Transact-SQL)
• sys.dm_xe_object_columns (Transact-SQL)