RELACE UDÁLOSTÍ (Transact-SQL)

platí pro:SQL Server azure SQL Managed Instance

Spustí nebo zastaví relaci události nebo změní konfiguraci relace události.

Syntaxe

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

Název existující relace události.

STAV = START | STOP

Spustí nebo zastaví relaci události. Argument STATE musí být zadán samostatně. Ve stejném ALTER EVENT SESSION příkazu se nedá kombinovat s žádnými dalšími argumenty.

PŘIDÁNÍ EVENT_SPECIFIER UDÁLOSTÍ <>

Identifikuje událost, která se má přidružit k relaci události. < > event_specifier je ve formě [event_module_guid].event_package_name. event_name, kde:

event_module_guid je identifikátor GUID modulu, který obsahuje událost.
event_package_name je balíček, který obsahuje událost.
event_name je název události.

Dostupné události lze najít spuštěním následujícího dotazu:

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

Přizpůsobitelné atributy události

Přizpůsobitelné atributy pro danou událost lze najít spuštěním následujícího dotazu:

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

Akce, která se má přidružit k události, kde:

event_module_guid je identifikátor GUID modulu, který obsahuje akci.
event_package_name je balíček, který obsahuje akci.
action_name je název akce.

Dostupné akce lze najít spuštěním následujícího dotazu:

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;

KDE <predicate_expression>

Určuje predikát výraz použitý k určení, jestli má být událost zpracována. Pokud <je predicate_expression> pravdivý, událost se dále zpracuje akcemi a cíli relace. Pokud <je predicate_expression> false, událost se zahodí, zabrání další akci a cílovému zpracování. Každý predikátový výraz je omezen na 3 000 znaků.

event_field_name

Název pole události, které identifikuje zdroj predikátu.

Pole události lze najít spuštěním následujícího dotazu:

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

Název globálního predikátu, kde:

event_module_guid je identifikátor GUID modulu, který obsahuje událost.
event_package_name je balíček, který obsahuje zdrojový objekt predikátu.
predicate_source_name je název predikátu.

Predikát zdroje lze najít spuštěním následujícího dotazu:

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

Název srovnávacího objektu predikátu, kde:

event_module_guid je identifikátor GUID modulu, který obsahuje událost.
event_package_name je balíček, který obsahuje porovnávací objekt predikátu.
predicate_compare_name je název porovnávače predikátu.

Srovnávací predikát lze najít spuštěním následujícího dotazu:

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

Libovolný číselný typ, který může být reprezentován jako 64bitové celé číslo.

Řetězec

Buď řetězec ANSI nebo Unicode vyžadovaný srovnávacím predikátem. Pro porovnávané funkce predikátu se neprovádí žádný implicitní převod typu řetězce. Předáním hodnoty neočekávaného typu dojde k chybě.

DROP EVENT <event_specifier>

Identifikuje událost, která se má odebrat z relace události. Specifikátor událostí je ve formě [event_module_guid]. event_package_name. event_name, kde:

event_module_guid je identifikátor GUID modulu, který obsahuje událost.
event_package_name je balíček, který obsahuje objekt akce.
event_name je objekt události.

< > event_specifier musí identifikovat událost, která byla dříve přidána do relace události.

PŘIDÁNÍ CÍLOVÉho <event_target_specifier>

Identifikuje cíl, který se má přidružit k relaci události. Specifikátor cíle události je ve formě [event_module_guid]. event_package_name. target_name, kde:

event_module_guid je identifikátor GUID modulu, který obsahuje událost.
event_package_name je balíček, který obsahuje objekt akce.
target_name je název cíle.

Dostupné cíle najdete spuštěním následujícího dotazu:

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;

Relace události může mít nula, jednu nebo mnoho cílů. Všechny cíle přidané do relace událostí se musí lišit. Nemůžete například přidat druhý event_file cíl do relace, která už má event_file cíl.

Další informace, včetně příkladů použití pro běžně používané cíle, naleznete v tématu Cíle rozšířených událostí.

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

Nastaví cílový parametr.

Pokud chcete zobrazit všechny cílové parametry a jejich popisy, spusťte následující dotaz a nahraďte target-name-placeholder ho názvem cíle, například event_file, ring_buffer, histogramatd.

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

Důležité

Pokud používáte cíl vyrovnávací paměti okruhu, doporučujeme nastavit MAX_MEMORYcílový parametr (odlišný od parametru MAX_MEMORYrelace ) na 1 024 kilobajtů (KB) nebo méně, abyste zabránili možnému zkrácení dat výstupu XML.

Další informace ocílových

DROP TARGET <event_target_specifier>

Identifikuje cíl, který se má odebrat z relace události. Specifikátor cíle události je ve formě [event_module_guid]. event_package_name. target_name, kde:

event_module_guid je identifikátor GUID modulu, který obsahuje událost.
event_package_name je balíček, který obsahuje objekt akce.
target_name je název cíle.

Specifikátor cíle události musí identifikovat cíl, který byl dříve přidán do relace události.

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

Určuje možnosti, které se mají použít s relací událostí.

MAX_MEMORY = velikost [ kB | MB ]

Určuje maximální velikost paměti, která se má přidělit relaci pro ukládání událostí do vyrovnávací paměti. Výchozí hodnota je 4 MB. velikost je celé číslo a může to být kilobajt (KB) nebo megabajt (MB). Maximální velikost nesmí překročit 2 GB (2 048 MB). Použití hodnot paměti v rozsahu GB se ale nedoporučuje.

EVENT_RETENTION_MODE = { ALLOW_SINGLE_EVENT_LOSS | ALLOW_MULTIPLE_EVENT_LOSS | NO_EVENT_LOSS }

Určuje režim uchovávání událostí, který se má použít pro zpracování ztráty událostí.

ALLOW_SINGLE_EVENT_LOSS

Událost může být ztracena z relace. Jedna událost se zahodí jenom v případě, že jsou všechny vyrovnávací paměti událostí plné. Ztráta jedné události, když jsou vyrovnávací paměti událostí plné, minimalizuje dopad na výkon a zároveň minimalizuje ztrátu dat ve zpracovaném streamu událostí.
ALLOW_MULTIPLE_EVENT_LOSS

Úplné vyrovnávací paměti událostí obsahující více událostí je možné z relace ztratit. Počet ztracených událostí závisí na velikosti paměti přidělené relaci, dělení paměti a velikosti událostí v vyrovnávací paměti. Tato možnost obecně zabraňuje dopadu na výkon na server, když jsou rychle vyplněny vyrovnávací paměti událostí, ale z relace může dojít ke ztrátě velkého počtu událostí.
NO_EVENT_LOSS

Není povolena žádná ztráta událostí. Tato možnost zajišťuje zachování všech vyvolaných událostí. Pomocí této možnosti vynutíte všechny úkoly, které aktivuje události, aby čekaly, až bude v vyrovnávací paměti událostí k dispozici mezera. Použití NO_EVENT_LOSS může způsobit zjištěné problémy s výkonem, když je relace událostí aktivní. Uživatelské relace a dotazy se můžou při čekání na vyprázdnění událostí z vyrovnávací paměti zastavit.

Poznámka:

Pro cíle souboru událostí ve službě Azure SQL Database a ve službě Azure SQL Managed Instance (se zásadami aktualizacesql Serveru 2025 nebo Always-up-to-date) se od června 2024 NO_EVENT_LOSS chová stejně jako ALLOW_SINGLE_EVENT_LOSS. Pokud zadáte NO_EVENT_LOSSupozornění s ID zprávy 25665, závažnost 10 a vrátí se zpráva This target doesn't support the NO_EVENT_LOSS event retention mode. The ALLOW_SINGLE_EVENT_LOSS retention mode is used instead. a relace se vytvoří.

Tato změna zabraňuje vypršení časového limitu připojení, zpoždění převzetí služeb při selhání a dalším problémům, které můžou snížit dostupnost databáze při NO_EVENT_LOSS použití s cíli souborů událostí v Úložišti objektů blob v Azure.

NO_EVENT_LOSS plánuje se odebrat jako podporovaný EVENT_RETENTION_MODE argument v budoucích aktualizacích služby Azure SQL Database a azure SQL Managed Instance. Nepoužívejte tuto funkci v nové vývojové práci a naplánujte úpravu aplikací, které tuto funkci aktuálně používají.

MAX_DISPATCH_LATENCY = { sekund SEKUNDY | INFINITE }

Určuje dobu, po kterou se události ukládají do vyrovnávací paměti před odesláním do cílů relace událostí. Ve výchozím nastavení je tato hodnota nastavená na 30 sekund.

sekundy SEKUNDY

Doba, v sekundách, počkat, než začnete vyprázdnit vyrovnávací paměti cílům. sekundy je celé číslo. Minimální hodnota latence je 1 sekunda. K určení latence INFINITE však lze použít hodnotu 0.
NEKONEČNÝ

Vyprázdnění vyrovnávacích pamětí cílům pouze v případě, že jsou vyrovnávací paměti plné nebo když se relace událostí zavře.

MAX_EVENT_SIZE = velikost [ kB | MB ]

Určuje maximální povolenou velikost událostí. MAX_EVENT_SIZE by měly být nastaveny pouze tak, aby povolily jednotlivé události větší než MAX_MEMORY; nastavení na méně než MAX_MEMORY vyvolá chybu. velikost je celé číslo a může to být kilobajt (KB) nebo megabajt (MB). Pokud je velikost zadaná v kilobajtech, minimální povolená velikost je 64 kB. Při nastavení MAX_EVENT_SIZE se kromě MAX_MEMORY vytvoří dvě vyrovnávací paměti a celková paměť používaná pro ukládání událostí do vyrovnávací paměti je MAX_MEMORY + 2 * MAX_EVENT_SIZE.

MEMORY_PARTITION_MODE = { NIKDO | PER_NODE | PER_CPU }

Určuje spřažení vyrovnávacích pamětí událostí. Jiné možnosti než NONE mají za následek více vyrovnávacích pamětí a vyšší spotřebu paměti, ale mohou se vyhnout kolizím a zlepšit výkon na větších počítačích.

ŽÁDNÝ

V instanci databázového stroje se vytvoří jedna sada vyrovnávacích pamětí.
PER_NODE

Pro každý uzel NUMA se vytvoří sada vyrovnávacích pamětí.
PER_CPU

Pro každý procesor se vytvoří sada vyrovnávacích pamětí.

TRACK_CAUSALITY = { ON | VYPNUTO }

Určuje, zda je sledována kauzalita události nebo ne. Pokud je tato možnost povolená, kauzalita umožňuje korelaci souvisejících událostí na různých serverových připojeních.

STARTUP_STATE = { ON | VYPNUTO }

Určuje, jestli se má tato relace událostí spustit automaticky při spuštění databázového stroje.

Poznámka:

Pokud STARTUP_STATE = ONse relace událostí spustí, když je databázový stroj zastaven a restartuje se. Chcete-li zahájit relaci událostí okamžitě, použijte ALTER EVENT SESSION ... ON SERVER STATE = START.

ON

Relace událostí se spustí při spuštění.
OFF

Relace událostí není spuštěna při spuštění.

MAX_DURATION = { doba trvání { SEKUNDY | MINUTY | HODINY | DAYS } | UNLIMITED }

Platí na: SQL Server 2025 (17.x)

NEOMEZENÝ

Způsobí, že se relace událostí spustí po neomezenou dobu, dokud se příkaz nezastaví ALTER EVENT SESSION ... STATE = STOP .
doba trvání SEKUNDY | MINUTY | HODINY | DNY

Způsobí, že se relace události automaticky zastaví po uplynutí zadaného času po spuštění relace. Maximální podporovaná doba trvání je 2 147 483 sekund nebo 35 792 minut nebo 596 hodin nebo 24 dní.

Další informace naleznete v tématu Relace událostí vázané na čas.

Poznámky

Další informace oargumentch

Argumenty ADD a DROP argumenty nelze použít ve stejném příkazu.

Povolení

SQL Server a Azure SQL Managed Instance vyžadují ALTER ANY EVENT SESSION oprávnění.

Azure SQL Database vyžaduje ALTER ANY DATABASE EVENT SESSION oprávnění v databázi.

Návod

SQL Server 2022 zavedl podrobnější oprávnění pro rozšířené události. Další informace najdete v tématu Blog: Nová podrobná oprávnění pro SQL Server 2022 a Azure SQL pro zlepšení dodržování poLP.

Examples

A. Spuštění a zastavení relace události

Chcete-li použít tento příklad s relacemi událostí databáze, nahraďte ON SERVER za ON DATABASE.

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

B. Přidání nových událostí do existující relace