SESJA WYDARZENIA ALTER (Transact-SQL)

Dotyczy:SQL Server Azure SQL Managed Instance

Uruchamia lub zatrzymuje sesję zdarzeń lub zmienia konfigurację sesji zdarzeń.

Składnia

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

Nazwa istniejącej sesji zdarzeń.

STATE = START | ZATRZYMAĆ

Uruchamia lub zatrzymuje sesję zdarzeń. Argument STATE należy określić samodzielnie. Nie można połączyć jej z żadnymi innymi argumentami w tej samej ALTER EVENT SESSION instrukcji.

DODAWANIE event_specifier ZDARZEŃ <>

Identyfikuje zdarzenie do skojarzenia z sesją zdarzeń. < > event_specifier jest w formie [event_module_guid].event_package_name. event_name gdzie:

event_module_guid jest identyfikatorEM GUID modułu, który zawiera zdarzenie.
event_package_name to pakiet zawierający zdarzenie.
event_name jest nazwą zdarzenia.

Dostępne zdarzenia można znaleźć, wykonując następujące zapytanie:

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 = <wartość> [ ,... n ] }

Atrybuty możliwe do dostosowania dla zdarzenia.

Atrybuty możliwe do dostosowania dla danego zdarzenia można znaleźć, wykonując następujące zapytanie:

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

Akcja do skojarzenia ze zdarzeniem, gdzie:

event_module_guid to identyfikator GUID modułu, który zawiera akcję.
event_package_name to pakiet zawierający akcję.
action_name jest nazwą akcji.

Dostępne akcje można znaleźć, wykonując następujące zapytanie:

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;

GDZIE <predicate_expression>

Określa wyrażenie predykatu używane do określania, czy zdarzenie ma być przetwarzane. Jeśli <predicate_expression> ma wartość true, zdarzenie jest przetwarzane dalej przez akcje i cele dla sesji. Jeśli <predicate_expression> ma wartość false, zdarzenie zostanie porzucone, unikając dodatkowej akcji i przetwarzania docelowego. Każde wyrażenie predykatu jest ograniczone do 3000 znaków.

event_field_name

Nazwa pola zdarzenia identyfikującego źródło predykatu.

Pola zdarzenia można znaleźć, wykonując następujące zapytanie:

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

Nazwa globalnego źródła predykatu, w którym:

event_module_guid jest identyfikatorEM GUID modułu, który zawiera zdarzenie.
event_package_name to pakiet zawierający obiekt źródłowy predykatu.
predicate_source_name jest nazwą źródła predykatu.

Źródła predykatu można znaleźć, wykonując następujące zapytanie:

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

Nazwa obiektu predykatu komparatora, gdzie:

event_module_guid jest identyfikatorEM GUID modułu, który zawiera zdarzenie.
event_package_name to pakiet zawierający obiekt komparatora predykatu.
predicate_compare_name jest nazwą predykatu komparatora.

Komplikatory predykatu można znaleźć, wykonując następujące zapytanie:

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

Dowolny typ liczbowy, który może być reprezentowany jako 64-bitowa liczba całkowita.

"ciąg"

Ciąg ANSI lub Unicode zgodnie z wymaganiami komparatora predykatu. Dla funkcji porównywania predykatu nie jest wykonywana niejawna konwersja typu ciągu. Przekazanie wartości nieoczekiwanego typu powoduje wystąpienie błędu.

EVENT <event_specifier>

Identyfikuje zdarzenie do usunięcia z sesji zdarzeń. Specyfikator zdarzeń ma postać [event_module_guid]. event_package_name. event_name gdzie:

event_module_guid jest identyfikatorEM GUID modułu, który zawiera zdarzenie.
event_package_name to pakiet zawierający obiekt akcji.
event_name jest obiektem zdarzenia.

< > event_specifier musi zidentyfikować zdarzenie, które zostało wcześniej dodane do sesji zdarzeń.

DODAWANIE event_target_specifier DOCELOWEJ <>

Identyfikuje element docelowy do skojarzenia z sesją zdarzeń. Specyfikator obiektu docelowego zdarzeń ma postać [event_module_guid]. event_package_name. target_name gdzie:

event_module_guid jest identyfikatorEM GUID modułu, który zawiera zdarzenie.
event_package_name to pakiet zawierający obiekt akcji.
target_name jest nazwą obiektu docelowego.

Dostępne elementy docelowe można znaleźć, wykonując następujące zapytanie:

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;

Sesja zdarzeń może mieć zero, jeden lub wiele obiektów docelowych. Wszystkie obiekty docelowe dodane do sesji zdarzeń muszą być różne. Na przykład nie można dodać drugiego event_file elementu docelowego do sesji, która ma już element docelowy event_file .

Aby uzyskać więcej informacji, w tym przykłady użycia dla często używanych obiektów docelowych, zobacz Obiekty docelowe zdarzeń rozszerzonych.

SET { target_parameter_name = <wartość> [ , ... n ] }

Ustawia parametr docelowy.

Aby wyświetlić wszystkie parametry docelowe i ich opisy, wykonaj następujące zapytanie, zastępując target-name-placeholder ciąg nazwą docelową, taką jak event_file, ring_buffer, histogramitp.

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

Ważne

Jeśli używasz docelowego buforu pierścienia, zalecamy ustawienie MAX_MEMORY parametru docelowego (różni się od parametru MAX_MEMORYsesji) na 1024 kilobajty (KB) lub mniej, aby uniknąć ewentualnego obcięcia danych wyjściowych XML.

Aby uzyskać więcej informacji o typach docelowych, zobacz Obiekty docelowe zdarzeń rozszerzonych.

DROP TARGET <event_target_specifier>

Identyfikuje element docelowy do usunięcia z sesji zdarzeń. Specyfikator obiektu docelowego zdarzeń ma postać [event_module_guid]. event_package_name. target_name gdzie:

event_module_guid jest identyfikatorEM GUID modułu, który zawiera zdarzenie.
event_package_name to pakiet zawierający obiekt akcji.
target_name jest nazwą obiektu docelowego.

Specyfikator obiektu docelowego zdarzeń musi zidentyfikować element docelowy, który został wcześniej dodany do sesji zdarzeń.

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

Określa opcje do użycia z sesją zdarzeń.

MAX_MEMORY = rozmiar [ KB | MB ]

Określa maksymalną ilość pamięci do przydzielenia do sesji na potrzeby buforowania zdarzeń. Wartość domyślna to 4 MB. rozmiar jest liczbą całkowitą i może być wartością kilobajtową (KB) lub megabajtową (MB). Maksymalna ilość nie może przekroczyć 2 GB (2048 MB). Jednak używanie wartości pamięci w zakresie GB nie jest zalecane.

EVENT_RETENTION_MODE = { ALLOW_SINGLE_EVENT_LOSS | ALLOW_MULTIPLE_EVENT_LOSS | NO_EVENT_LOSS }

Określa tryb przechowywania zdarzeń, który ma być używany do obsługi utraty zdarzeń.

ALLOW_SINGLE_EVENT_LOSS

Zdarzenie można utracić z sesji. Pojedyncze zdarzenie jest porzucane tylko wtedy, gdy wszystkie zdarzeń są pełne. Utrata pojedynczego zdarzenia, gdy zdarzeń są pełne, minimalizuje wpływ na wydajność, jednocześnie minimalizując utratę danych w przetworzonym strumieniu zdarzeń.
ALLOW_MULTIPLE_EVENT_LOSS

Pełne zdarzeń zawierające wiele zdarzeń można utracić z sesji. Liczba utraconych zdarzeń zależy od rozmiaru pamięci przydzielonego do sesji, partycjonowania pamięci i rozmiaru zdarzeń w buforze. Ta opcja zwykle pozwala uniknąć wpływu na wydajność serwera, gdy zdarzeń są szybko wypełniane, ale duża liczba zdarzeń może zostać utracona z sesji.
NO_EVENT_LOSS

Żadna utrata zdarzeń nie jest dozwolona. Ta opcja gwarantuje, że wszystkie zgłoszone zdarzenia zostaną zachowane. Użycie tej opcji wymusza, aby wszystkie zadania uruchamiające zdarzenia czekały, aż miejsce będzie dostępne w buforze zdarzeń. Użycie NO_EVENT_LOSS może powodować wykrywalne problemy z wydajnością, gdy sesja zdarzeń jest aktywna. Sesje użytkowników i zapytania mogą zostać wstrzymane podczas oczekiwania na opróżnienie z buforu zdarzeń.

Uwaga / Notatka

W przypadku obiektów docelowych plików zdarzeń w usłudze Azure SQL Database i w usłudze Azure SQL Managed Instance (z programem SQL Server 2025 lub zawszeup-to-dateupdate policy), począwszy od czerwca 2024 r., NO_EVENT_LOSS zachowuje się tak samo jak ALLOW_SINGLE_EVENT_LOSS. Jeśli określisz NO_EVENT_LOSSwartość , zostanie zwrócone ostrzeżenie o identyfikatorze komunikatu 25665, ważność 10 i zostanie zwrócony komunikat This target doesn't support the NO_EVENT_LOSS event retention mode. The ALLOW_SINGLE_EVENT_LOSS retention mode is used instead. , a sesja zostanie utworzona.

Ta zmiana pozwala uniknąć przekroczenia limitu czasu połączenia, opóźnień trybu failover i innych problemów, które mogą zmniejszyć dostępność bazy danych, gdy NO_EVENT_LOSS są używane z miejscami docelowymi plików zdarzeń w usłudze Azure Blob Storage.

NO_EVENT_LOSS program jest planowany do usunięcia jako obsługiwany EVENT_RETENTION_MODE argument w przyszłych aktualizacjach usług Azure SQL Database i Azure SQL Managed Instance. Unikaj używania tej funkcji w nowych pracach programistycznych i zaplanuj modyfikowanie aplikacji, które obecnie korzystają z tej funkcji.

MAX_DISPATCH_LATENCY = { sekundy | NIESKOŃCZONY }

Określa czas buforowania zdarzeń w pamięci przed wysłaniem do celów sesji zdarzeń. Domyślnie ta wartość jest ustawiona na 30 sekund.

Sekund SEKUND

Czas oczekiwania w sekundach przed rozpoczęciem opróżniania do obiektów docelowych. sekundy to liczba całkowita. Minimalna wartość opóźnienia to 1 sekunda. Można jednak użyć wartości 0 do określenia nieskończonego opóźnienia.
NIESKOŃCZONY

Opróżnij do obiektów docelowych tylko wtedy, gdy są pełne lub gdy sesja zdarzenia zostanie zamknięta.

MAX_EVENT_SIZE = rozmiar [ KB | MB ]

Określa maksymalny dozwolony rozmiar zdarzeń. MAX_EVENT_SIZE należy ustawić tylko tak, aby zezwalać na pojedyncze zdarzenia większe niż MAX_MEMORY; ustawienie go na wartość mniejszą niż MAX_MEMORY zgłasza błąd. rozmiar jest liczbą całkowitą i może być wartością kilobajtową (KB) lub megabajtową (MB). Jeśli rozmiar jest określony w kilobajtach, minimalny dozwolony rozmiar wynosi 64 KB. Po ustawieniu MAX_EVENT_SIZE dwa rozmiaru są tworzone oprócz MAX_MEMORY, a łączna ilość pamięci używanej do buforowania zdarzeń wynosi MAX_MEMORY + 2 * MAX_EVENT_SIZE.

MEMORY_PARTITION_MODE = { NIKT | PER_NODE | PER_CPU }

Określa koligację zdarzeń. Opcje inne niż NONE powodują więcej i większe zużycie pamięci, ale mogą uniknąć rywalizacji i zwiększyć wydajność na większych maszynach.

ŻADEN

Pojedynczy zestaw jest tworzony w wystąpieniu aparatu bazy danych.
PER_NODE

Dla każdego węzła NUMA jest tworzony zestaw.
PER_CPU

Dla każdego procesora CPU jest tworzony zestaw.

TRACK_CAUSALITY = { ON | WYŁ. }

Określa, czy przyczynowość zdarzenia jest śledzona. Jeśli ta opcja jest włączona, przyczynowość umożliwia skorelowanie powiązanych zdarzeń na różnych połączeniach serwera.

STARTUP_STATE = { ON | WYŁ. }

Określa, czy uruchamiać tę sesję zdarzeń automatycznie po uruchomieniu aparatu bazy danych.

Uwaga / Notatka

Jeśli STARTUP_STATE = ON, sesja zdarzeń rozpoczyna się, gdy aparat bazy danych zostanie zatrzymany, a następnie ponownie uruchomiony. Aby natychmiast rozpocząć sesję zdarzeń, użyj polecenia ALTER EVENT SESSION ... ON SERVER STATE = START.

ON

Sesja zdarzeń jest uruchamiana podczas uruchamiania.
OFF

Sesja zdarzeń nie jest uruchamiana podczas uruchamiania.

MAX_DURATION = { czas trwania { SEKUNDY | MINUTY | GODZINY | DNI } | NIEOGRANICZONE }

Dotyczy do: SQL Server 2025 (17.x)

NIEOGRANICZONY

Powoduje, że sesja zdarzeń jest uruchamiana przez czas nieokreślony, dopóki nie zostanie zatrzymana przy użyciu instrukcji ALTER EVENT SESSION ... STATE = STOP .
czas trwania SEKUNDY | MINUTY | GODZINY | DNI

Powoduje automatyczne zatrzymanie sesji zdarzeń po upływie określonego czasu po rozpoczęciu sesji. Maksymalny obsługiwany czas trwania to 2147 483 sekundy lub 35 792 minut lub 596 godzin lub 24 dni.

Aby uzyskać więcej informacji, zobacz Sesje zdarzeń związane z czasem.

Uwagi

Aby uzyskać więcej informacji na temat argumentów sesji zdarzeń, zobacz Sesje zdarzeń rozszerzonych.

Argumenty ADD i DROP nie mogą być używane w tej samej instrukcji.

Permissions

Program SQL Server i usługa Azure SQL Managed Instance wymagają ALTER ANY EVENT SESSION uprawnienia.

Usługa Azure SQL Database wymaga ALTER ANY DATABASE EVENT SESSION uprawnienia w bazie danych.

Wskazówka

Program SQL Server 2022 wprowadził bardziej szczegółowe uprawnienia dla zdarzeń rozszerzonych. Aby uzyskać więcej informacji, zobacz Blog: Nowe szczegółowe uprawnienia dla programu SQL Server 2022 i usługi Azure SQL w celu poprawy zgodności z funkcją PoLP.

Przykłady

A. Uruchamianie i zatrzymywanie sesji zdarzeń

Aby użyć tego przykładu z sesjami zdarzeń bazy danych, zastąp element ON SERVER .ON DATABASE

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

B. Dodawanie nowych zdarzeń do istniejącej sesji