ALTER EVENT SESSION (Transact-SQL)

применимо к:SQL Server Управляемому экземпляру SQL Azure

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

Синтаксис

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

Аргументы

event_session_name

Имя существующего сеанса событий.

STATE = START | ОСТАНОВКА

Запускает или останавливает сеанс событий. Аргумент STATE должен быть указан самостоятельно. Его нельзя объединить с другими аргументами в том же ALTER EVENT SESSION операторе.

ДОБАВЛЕНИЕ EVENT_SPECIFIER СОБЫТИЯ <>

Определяет событие, которое необходимо связать с сеансом событий. < > event_specifier находится в виде [event_module_guid].event_package_name. event_name, где:

event_module_guid — идентификатор GUID для модуля, содержащего событие;
event_package_name — это пакет, содержащий событие.
event_name — это имя события.

Доступные события можно найти, выполнив следующий запрос:

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 = <значение> [ ,... n ] }

Настраиваемые атрибуты для события.

Настраиваемые атрибуты для данного события можно найти, выполнив следующий запрос:

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

Действие, которое необходимо связать с событием, где:

event_module_guid — это GUID модуля, содержащего действие.
event_package_name — это пакет, содержащий действие.
action_name — это имя действия.

Доступные действия можно найти, выполнив следующий запрос:

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;

ГДЕ <predicate_expression>

Задает выражение предиката, используемое, чтобы определить необходимость обработки события. Если <predicate_expression> имеет значение true, то обработка события продолжается действиями и целевыми объектами сеанса. Если <predicate_expression> имеет значение false, событие удаляется, избегая дополнительных действий и целевой обработки. Каждое выражение предиката ограничено 3000 символами.

event_field_name

Имя поля события, определяющего источник предиката.

Поля для события можно найти, выполнив следующий запрос:

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

Имя глобального источника предиката, в котором:

event_module_guid — идентификатор GUID для модуля, содержащего событие;
event_package_name — это пакет, содержащий исходный объект предиката.
predicate_source_name — это имя источника предиката.

Источники предиката можно найти, выполнив следующий запрос:

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

Имя объекта сравнения предиката, где:

event_module_guid — идентификатор GUID для модуля, содержащего событие;
event_package_name — это пакет, содержащий объект сравнения предиката.
predicate_compare_name — это имя предиката сравнения.

Компатеры предиката можно найти, выполнив следующий запрос:

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;

номер

Любой числовый тип, который может быть представлен как 64-разрядное целое число.

"string"

Строка ANSI или Юникод, необходимые для компаратора предиката. Для функций предикатного сравнения не выполняется неявное преобразование строкового типа. Передача значения неожиданного типа приводит к ошибке.

СОБЫТИЕ <DROP event_specifier>

Определяет событие для удаления из сеанса событий. Описатель событий находится в виде [event_module_guid]. event_package_name. event_name, где:

event_module_guid — идентификатор GUID для модуля, содержащего событие;
event_package_name — пакет, который содержит объект действия;
event_name — объект события.

< > event_specifier должен определить событие, которое ранее было добавлено в сеанс событий.

ДОБАВЛЕНИЕ ЦЕЛЕВОГО <EVENT_TARGET_SPECIFIER>

Определяет целевой объект для связывания с сеансом событий. Описатель целевого объекта события находится в виде [event_module_guid]. event_package_name. target_name, где:

event_module_guid — идентификатор GUID для модуля, содержащего событие;
event_package_name — пакет, который содержит объект действия;
target_name — это имя целевого объекта.

Доступные целевые объекты можно найти, выполнив следующий запрос:

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;

Сеанс событий может иметь ноль, один или несколько целевых объектов. Все целевые объекты, добавленные в сеанс событий, должны отличаться. Например, нельзя добавить второй event_file целевой объект в сеанс, который уже имеет целевой event_file объект.

Дополнительные сведения, включая примеры использования для часто используемых целевых объектов, см. в разделе целевых объектов расширенных событий.

SET { target_parameter_name = <значение> [ , ... n ] }

Задает параметр целевого объекта.

Чтобы просмотреть все целевые параметры и их описания, выполните следующий запрос, заменив target-name-placeholder целевое имя, например event_file, ring_bufferи histogramт. д.

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

Это важно

Если вы используете целевой объект буфера кольца, рекомендуется задать MAX_MEMORYцелевой параметр (отличный от MAX_MEMORY параметра сеанса) значение 1024 килобайта (КБ) или меньше, чтобы избежать возможного усечения данных выходных данных XML.

Дополнительные сведения о целевых типах см. в разделе "Целевые объекты расширенных событий".

DROP TARGET <event_target_specifier>

Определяет целевой объект для удаления из сеанса событий. Описатель целевого объекта события находится в виде [event_module_guid]. event_package_name. target_name, где:

event_module_guid — идентификатор GUID для модуля, содержащего событие;
event_package_name — пакет, который содержит объект действия;
target_name — это имя целевого объекта.

Описатель целевого объекта события должен определить целевой объект, который ранее был добавлен в сеанс событий.

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

Указывает параметры, используемые в сеансе событий.

MAX_MEMORY = размер [ КБ | МБ ]

Задает максимальный объем памяти, выделенной в сеансе для буферов событий. Значение по умолчанию — 4 Мб. размер — целое значение, которое может указываться в килобайтах (Кб) или мегабайтах (Мб). Максимальная сумма не может превышать 2 ГБ (2048 МБ). Однако использование значений памяти в диапазоне ГБ не рекомендуется.

EVENT_RETENTION_MODE = { ALLOW_SINGLE_EVENT_LOSS | ALLOW_MULTIPLE_EVENT_LOSS | NO_EVENT_LOSS }

Задает режим хранения событий, используемый для обработки потери события.

ALLOW_SINGLE_EVENT_LOSS

Возможна потеря события в сеансе. Если все буферы событий полны, то удаляется только одно событие. Потеря одного события при заполнении буферов событий сводит к минимуму влияние на производительность, а также минимизирует потерю данных в обработанном потоке событий.
ALLOW_MULTIPLE_EVENT_LOSS

Из сеанса могут быть потеряны полные буферы событий, содержащие несколько событий. Число потерянных событий зависит от размера памяти, выделенной для сеанса, способа секционирования памяти и размера событий в буфере. Этот параметр обычно позволяет избежать влияния на производительность сервера при быстром заполнении буферов событий, но из сеанса может быть потеряно большое количество событий.
NO_EVENT_LOSS

Потеря событий не разрешена. Этот параметр обеспечивает сохранение всех произошедших событий. При использовании этого параметра все задачи, которые инициируют события, должны ждать освобождения пространства в буфере событий. Использование NO_EVENT_LOSS может вызвать обнаруженные проблемы с производительностью во время активного сеанса событий. Сеансы и запросы пользователей могут зависать при ожидании очистки событий из буфера.

Замечание

Для целевых объектов файла событий в Базе данных SQL Azure и Управляемом экземпляре SQL Azure (с политикой обновления sql Server 2025 или Always-up-to-date), начиная с июня 2024 года, NO_EVENT_LOSS действует так же, какALLOW_SINGLE_EVENT_LOSS. Если указать NO_EVENT_LOSS, предупреждение с идентификатором сообщения 25665, серьезностью 10 и возвращается сообщение This target doesn't support the NO_EVENT_LOSS event retention mode. The ALLOW_SINGLE_EVENT_LOSS retention mode is used instead. , а сеанс создается.

Это изменение позволяет избежать времени ожидания подключения, задержек отработки отказа и других проблем, которые могут снизить доступность базы данных при NO_EVENT_LOSS использовании с целевыми объектами файлов событий в хранилище BLOB-объектов Azure.

NO_EVENT_LOSS планируется удалить в качестве поддерживаемого EVENT_RETENTION_MODE аргумента в будущих обновлениях базы данных SQL Azure и Управляемого экземпляра SQL Azure. Избегайте использования этого компонента в новых разработках и запланируйте изменение существующих приложений, в которых он применяется.

MAX_DISPATCH_LATENCY = { секунды | INFINITE }

Задает промежуток времени, в течение которого события находятся в буферной памяти перед отправкой в цели сеанса событий. По умолчанию это значение равно 30 секундам.

товары второго сорта ТОВАРЫ ВТОРОГО СОРТА

Время ожидания (в секундах) перед началом выгрузки содержимого буферов в цели. seconds является целым числом. Минимальное значение задержки составляет 1 секунду. Чтобы задать неограниченную задержку (INFINITE), можно использовать значение 0.
БЕСКОНЕЧНЫЙ

Запись на диск буферов в цели только при заполнении буферов или закрытии сеанса событий.

MAX_EVENT_SIZE = размер [ КБ | МБ ]

Задает максимальный допустимый размер для событий. MAX_EVENT_SIZE следует задать только для разрешения отдельных событий, превышающих MAX_MEMORY; Если задать значение меньше MAX_MEMORY возникает ошибка. size — целое значение, которое может быть представлено значением в килобайтах (КБ) или мегабайтах (МБ). Если значение size указано в килобайтах, то минимально допустимое значение — 64 KБ. Если задано MAX_EVENT_SIZE, в дополнение к MAX_MEMORY создаются два буфера размера , а общая память, используемая для буферизации событий, MAX_MEMORY + 2 * MAX_EVENT_SIZE.

MEMORY_PARTITION_MODE = { НЕТ | PER_NODE | PER_CPU }

Указывает сходство буферов событий. Варианты, отличные от NONE того, что приводит к большему объему буферов и более высокому потреблению памяти, но могут избежать конфликтов и повысить производительность на больших компьютерах.

НИКАКОЙ

В экземпляре ядра СУБД создается один набор буферов.
PER_NODE

Для каждого узла NUMA создается набор буферов.
PER_CPU

Набор буферов создается для каждого ЦП.

TRACK_CAUSALITY = { ON | OFF }

Указывает, отслеживается ли причинность события. Если отслеживание включено, то причинность позволяет коррелировать связанные события в различных серверных соединениях.

STARTUP_STATE = { ON | OFF }

Указывает, следует ли автоматически запускать этот сеанс событий при запуске ядра СУБД.

Замечание

Если STARTUP_STATE = ONсеанс событий запускается, когда ядро СУБД остановлено, а затем перезапущено. Чтобы немедленно запустить сеанс событий, используйте .ALTER EVENT SESSION ... ON SERVER STATE = START

DNS

Сеанс событий запускается при запуске.
ВЫКЛ.

Сеанс событий не запускается при запуске.

MAX_DURATION = { длительность времени { СЕКУНД | MINUTES | ЧАСЫ | DAYS } | НЕОГРАНИЧЕННЫЙ }

Применимо к: SQL Server 2025 (17.x)

НЕОГРАНИЧЕННЫЙ

Вызывает выполнение сеанса событий на неопределенный срок после запуска, пока не будет остановлено использование инструкции ALTER EVENT SESSION ... STATE = STOP .
длительность времени СЕКУНДы | MINUTES | ЧАСЫ | Дни недели

Вызывает автоматическую остановку сеанса событий после истечения указанного времени после запуска сеанса. Максимальная поддерживаемая длительность — 2 147 483 секунды, 35 792 минуты или 596 часов или 24 дня.

Дополнительные сведения см. в разделе "Сеансы событий с привязкой к времени".

Замечания

Дополнительные сведения о аргументах сеанса событий см. в разделе "Расширенные события".

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

Разрешения

Для SQL Server и Управляемого ALTER ANY EVENT SESSION экземпляра SQL Azure требуется разрешение.

Для базы данных SQL Azure требуется ALTER ANY DATABASE EVENT SESSION разрешение в базе данных.

Совет

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

Примеры

А. Запуск и остановка сеанса событий

Чтобы использовать этот пример с сеансами событий базы данных, замените ON SERVER на ON DATABASE.

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

В. Добавление новых событий в существующий сеанс