ALTER EVENT SESSION (Transact-SQL)

Статья
05/15/2024

Область применения: SQL Server Управляемый экземпляр SQL Azure

Запускает или останавливает сеанс событий или изменяет конфигурацию сеанса.

Синтаксис

ALTER EVENT SESSION event_session_name  
ON SERVER  
{  
    [ [ {  <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 } ]  
}

Аргументы

Термин	Определение
event_session_name	Имя существующего сеанса событий.
STATE = START \| ОСТАНОВКА	Запускает или останавливает сеанс событий. Это аргумент действителен, только если к объекту сеанса событий применяется ALTER EVENT SESSION.
ADD EVENT <event_specifier>	Связывает событие, определенное аргументом <event_specifier>, с сеансом событий.
[event_module_guid].event_package_name.event_name	Имя события в пакете событий, где: - event_module_guid — идентификатор GUID для модуля, содержащего событие; - event_package_name — пакет, который содержит объект действия; - event_name — объект события. События отображаются в представлении sys.dm_xe_objects со значением object_type, равным "event".
SET { event_customizable_attribute= <value> [ ,...n] }	Указывает настраиваемые атрибуты для события. Настраиваемые атрибуты отображаются в представлении sys.dm_xe_object_columns со значением column_type, равным "customizable", и object_name = event_name.
ACTION ( { [event_module_guid].event_package_name.action_name [ ,...n] } )	Действие, связанное с сеансом событий, где: - event_module_guid — идентификатор GUID для модуля, содержащего событие; - event_package_name — пакет, который содержит объект действия; - action_name — объект действия. Действия отображаются в представлении sys.dm_xe_objects со значением object_type, равным "action".
WHERE <predicate_expression>	Задает выражение предиката, используемое, чтобы определить необходимость обработки события. Если <predicate_expression> имеет значение true, то обработка события продолжается действиями и целевыми объектами сеанса. Если <predicate_expression> имеет значение false, для этого события не происходит действие и целевая обработка. Выражения предиката ограничены 3000 символами, ограничивающими строковые аргументы.
event_field_name	Имя поля события, которое идентифицирует источник предиката.
[event_module_guid].event_package_name.predicate_source_name	Имя глобального источника предиката, где: - event_module_guid — идентификатор GUID для модуля, содержащего событие; - event_package_name — пакет, который содержит объект предиката; - predicate_source_name определен в представлении sys.dm_xe_objects как object_type со значением "pred_source".
[event_module_guid].event_package_name.predicate_compare_name	Имя объекта предиката, связываемого с событием, где: - event_module_guid — идентификатор GUID для модуля, содержащего событие; - event_package_name — пакет, который содержит объект предиката; - predicate_compare_name — глобальный источник, определенный в представлении sys.dm_xe_objects со значением object_type, равным "pred_compare".
DROP EVENT <event_specifier>	Удаляет событие, обозначенное <event_specifier>. <event_specifier> должен быть допустимым в рамках сеанса события.
ADD TARGET <event_target_specifier>	Связывает целевой объект, определенный аргументом <event_target_specifier>, с сеансом событий.
[event_module_guid].event_package_name.target_name	Имя целевого объекта в сеансе событий, где: - event_module_guid — идентификатор GUID для модуля, содержащего событие; - event_package_name — пакет, который содержит объект действия; - target_name представляет собой действие. Действия отображаются в представлении sys.dm_xe_objects как object_type со значением "target".
SET { target_parameter_name= <value> [, ...n] }	Задает параметр целевого объекта. Параметры цели отображаются в представлении sys.dm_xe_object_columns со значением column_type, равным "customizable", и object_name = target_name. Примечание. Если вы используете целевой объект кольцевого буфера, рекомендуется задать для целевого параметра max_memory значение 2048 килобайт (КБ), чтобы избежать возможного усечения данных выходных данных XML. Дополнительные сведения об использовании разных типов целевых объектов см. в статье Цели расширенных событий SQL Server.
DROP TARGET <event_target_specifier>	Удаляет целевой объект, обозначенный <event_target_specifier>. <event_target_specifier> должен быть допустимым в рамках сеанса события.
EVENT_RETENTION_MODE = { ALLOW_SINGLE_EVENT_LOSS \| ALLOW_MULTIPLE_EVENT_LOSS \| NO_EVENT_LOSS }	Задает режим хранения событий, используемый для обработки потери события. ALLOW_SINGLE_EVENT_LOSS Возможна потеря события в сеансе. Если все буферы событий полны, то удаляется только одно событие. Потеря одного события при заполнении буферов событий обеспечивает допустимые характеристики производительности SQL Server, минимизируя потерю данных в обработанном потоке событий. ALLOW_MULTIPLE_EVENT_LOSS Из сеанса могут быть потеряны полные буферы событий, содержащие несколько событий. Число потерянных событий зависит от размера памяти, выделенной для сеанса, способа секционирования памяти и размера событий в буфере. Этот параметр уменьшает влияние быстрого заполнения буферов событий на производительность сервера, но возможна потеря большого числа событий в сеансе. NO_EVENT_LOSS Потеря событий не разрешена. Этот параметр обеспечивает сохранение всех произошедших событий. При использовании этого параметра все задачи, которые инициируют события, должны ждать освобождения пространства в буфере событий. Это может привести к заметному снижению производительности во время активного сеанса событий. Соединения пользователя могут простаивать при ожидании событий, данные которых должны быть записаны на диск из буфера. Для целевых объектов файлов событий в База данных SQL Azure работает так же, как и ALLOW_SINGLE_EVENT_LOSS. Дополнительные сведения см. в EVENT_RETENTION_MODE.
MAX_DISPATCH_LATENCY = { seconds SECONDS \| INFINITE }	Задает промежуток времени, в течение которого события находятся в буферной памяти перед отправкой в цели сеанса событий. Минимальное значение задержки составляет 1 секунду. Чтобы задать неограниченную задержку (INFINITE), можно использовать значение 0. По умолчанию это значение равно 30 секундам. seconds SECONDS Время ожидания (в секундах) перед началом выгрузки содержимого буферов в цели. seconds является целым числом. INFINITE Запись на диск буферов в цели только при заполнении буферов или закрытии сеанса событий. Примечание. MAX_DISPATCH_LATENCY = 0 SECONDS эквивалентно MAX_DISPATCH_LATENCY = INFINITE.
MAX_EVENT_SIZE =size [ KB \| MB ]	Задает максимальный допустимый размер для событий. MAX_EVENT_SIZE следует задать только для разрешения отдельных событий, превышающих MAX_MEMORY; Если задать значение меньше MAX_MEMORY возникает ошибка. size — целое значение, которое может быть представлено значением в килобайтах (КБ) или мегабайтах (МБ). Если значение size указано в килобайтах, то минимально допустимое значение — 64 KБ. Если задано значение MAX_EVENT_SIZE, то в дополнение к MAX_MEMORY создаются два буфера размером size. Это значит, что общий объем памяти, используемой для буферизации событий, составляет MAX_MEMORY + 2 * MAX_EVENT_SIZE.
MEMORY_PARTITION_MODE = { NONE \| PER_NODE \| PER_CPU }	Задает место, в котором создаются буферы событий. NONE Один набор буферов создается в экземпляре SQL Server. PER NODE — набор буферов создается в каждом узле NUMA. PER CPU — набор буферов создается для каждого ЦП.
TRACK_CAUSALITY = { ON \| OFF }	Указывает, будут ли отслеживаться причинно-следственные связи. Если отслеживание включено, то причинность позволяет коррелировать связанные события в различных серверных соединениях.
STARTUP_STATE = { ON \| OFF }	Указывает, следует ли автоматически запускать этот сеанс событий при запуске SQL Server. Если STARTUP_STATE=ON сеанс событий запускается только в том случае, если SQL Server остановлен, а затем перезапущен. ON — сеанс событий запускается при начальном запуске. OFF — сеанс событий не запускается при начальном запуске.

Замечания

Аргументы ADD и DROP аргументы нельзя использовать в той же инструкции.

Разрешения

Требуется разрешение ALTER ANY EVENT SESSION.

Совет

В SQL Server 2022 появилось несколько новых более подробных разрешений для расширенных событий, дополнительные сведения см . в блоге: новые детализированные разрешения для SQL Server 2022 и Azure SQL для улучшения соблюдения с помощью PoLP.

Примеры

Следующий пример запускает сеанс событий, получает динамическую статистику сеанса, а затем добавляет два события в существующий сеанс.

-- Start the event session  
ALTER EVENT SESSION test_session ON SERVER  
STATE = start;  
GO  

-- Obtain live session statistics   
SELECT * FROM sys.dm_xe_sessions;  
SELECT * FROM sys.dm_xe_session_events;  
GO  
  
-- Add new events to the session  
ALTER EVENT SESSION test_session ON SERVER  
ADD EVENT sqlserver.database_transaction_begin,  
ADD EVENT sqlserver.database_transaction_end;  
GO

Поделиться через

ALTER EVENT SESSION (Transact-SQL)

Синтаксис

Аргументы

Замечания

Разрешения

Примеры

См. также

Обратная связь

Дополнительные ресурсы