CREATE EVENT SESSION (Transact-SQL)

Статья
05/30/2024

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

Создает сеанс расширенных событий, который идентифицирует источник событий, цели и параметры сеанса событий.

Синтаксис

CREATE EVENT SESSION event_session_name
ON { SERVER | DATABASE }
{  
    <event_definition> [ ,...n]
    [ <event_target_definition> [ ,...n] ]
    [ WITH ( <event_session_options> [ ,...n] ) ]
}
;

<event_definition>::=
{
    ADD EVENT [event_module_guid].event_package_name.event_name
         [ ( {
                 [ SET { event_customizable_attribute = <value> [ ,...n] } ]
                 [ ACTION ( { [event_module_guid].event_package_name.action_name [ ,...n] } ) ]
                 [ WHERE <predicate_expression> ]
        } ) ]
}

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

<event_target_definition>::=
{
    ADD TARGET [event_module_guid].event_package_name.target_name
        [ ( SET { target_parameter_name = <value> [ ,...n] } ) ]
}

<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

Определяемое пользователем имя для сеанса событий. event_session_name является буквенно-цифровым, может быть до 128 символов, должен быть уникальным в экземпляре SQL Server и должен соответствовать правилам идентификаторов.

ADD EVENT [ 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'.

number — любой числовой тип, включая decimal. Ограничения: недостаток доступной физической памяти или слишком большое число, которое невозможно представить 64-разрядным целым.

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

ADD TARGET [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] }

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

Чтобы просмотреть все целевые параметры и их описания, выполните следующий запрос, заменив target-name заполнитель именем целевого объекта, например 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';

Внимание

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

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

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

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

MAX_MEMORY =size [ KB | MB ]

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

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

Примечание.

Для целевых объектов файла событий в База данных SQL Azure и в Управляемый экземпляр SQL Azure с политикой обновления всегда актуальной версии, начиная с июня 2024 года, NO_EVENT_LOSS ведет себя так же, как и ALLOW_SINGLE_EVENT_LOSS. Если указать NO_EVENT_LOSS, предупреждение с идентификатором сообщения 25665, серьезностью 10 и сообщением , что целевой объект не поддерживает режим хранения событий NO_EVENT_LOSS. Вместо этого используется режим хранения ALLOW_SINGLE_EVENT_LOSS. возвращается и создается сеанс.

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

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

MAX_DISPATCH_LATENCY = { seconds SECONDS | INFINITE }

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

seconds SECONDS — время ожидания в секундах перед началом выгрузки содержимого буферов в целевые объекты. seconds является целым числом. Минимальное значение задержки составляет 1 секунду. Чтобы задать неограниченную задержку (INFINITE), можно использовать значение 0.

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 создаются два буфера размера , а общая память, используемая для буферизации событий, MAX_MEMORY + 2 * MAX_EVENT_SIZE.

MEMORY_PARTITION_MODE = { NONE | PER_NODE | PER_CPU }

Задает место, в котором создаются буферы событий.

НЕТ Одного набора буферов создается в экземпляре SQL Server.

PER_NODE — Набор буферов, создаваемый для каждого узла NUMA.

PER_CPU — набор буферов, создаваемый для каждого ЦП.

TRACK_CAUSALITY = { ON | OFF }

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

STARTUP_STATE = { ON | OFF }

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

Примечание.

Если STARTUP_STATE = ONсеанс событий начнется только в том случае, если SQL Server остановлен, а затем перезапущен.

ON: сеанс событий запускается при начальном запуске.

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

Замечания

Приоритеты выполнения логических операторов распределяются следующим образом: NOT (наивысший приоритет), AND, OR (низший приоритет).

Разрешения

Для SQL Server и Управляемый экземпляр SQL требуется CREATE ANY EVENT SESSION (введено в SQL Server 2022) или ALTER ANY EVENT SESSION разрешение.

В Базе данных SQL требуется соответствующее разрешение ALTER ANY DATABASE EVENT SESSION.

Совет

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

Примеры

Пример для SQL Server

В следующем примере демонстрируется, как создать сеанс событий с именем test_session. В этом примере добавляются два события, а также используется цель средства отслеживания событий для Windows.

IF EXISTS(SELECT * FROM sys.server_event_sessions WHERE name='test_session')
    DROP EVENT session test_session ON SERVER;
GO
CREATE EVENT SESSION test_session
ON SERVER
    ADD EVENT sqlos.async_io_requested,
    ADD EVENT sqlserver.lock_acquired
    ADD TARGET package0.etw_classic_sync_target
        (SET default_etw_session_logfile_path = N'C:\demo\traces\sqletw.etl' )
    WITH (MAX_MEMORY=4MB, MAX_EVENT_SIZE=4MB);
GO

Пример SQL Azure

В управляемом экземпляре SQL Azure или в базе данных SQL Azure сохраните файлы .xel в хранилище BLOB-объектов Azure. Вы можете использовать sys.fn_xe_file_target_read_file для чтения из сеансов расширенных событий, которые создаются и сохраняются в хранилище BLOB-объектов Azure. В качеств примера пошагового руководства проверьте целевой код файла событий расширенных событий в базе данных SQL Azure и управляемом экземпляре SQL Azure.

Примеры кода могут отличаться для базы данных SQL Azure и управляемого экземпляра SQL

Некоторые примеры кода Transact-SQL, написанные для SQL Server, нуждаются в небольших изменениях для запуска в Azure. Одна из категорий таких примеров кода включает представления каталога, префиксы имен которых отличаются в зависимости от типа ядра СУБД:

server_ - префикс для SQL Server и Управляемый экземпляр SQL Azure
database_ - префикс для База данных SQL Azure и Управляемый экземпляр SQL

База данных SQL Azure поддерживает только сеансы событий с областью действия базы данных. SQL Server Management Studio (SSMS) полностью поддерживает сеансы событий с областью действия базы данных для База данных SQL Azure: узел расширенных событий, содержащий сеансы с областью базы данных, отображаются в каждой базе данных в обозреватель объектов.

Управляемый экземпляр SQL Azure поддерживает как сеансы уровня базы данных, так и сеансы уровня сервера. SSMS полностью поддерживает сеансы на уровне сервера для Управляемого экземпляра SQL: узел Расширенные события, содержащий все сеансы на уровне сервера, отображается в папке Управление для каждого управляемого экземпляра в обозревателе объектов.

Примечание.

Для управляемых экземпляров рекомендуется использовать сеансы на уровне сервера. Сеансы с областью базы данных не отображаются в обозреватель объектов в SSMS для Управляемый экземпляр SQL Azure. Сеансы с областью базы данных могут запрашиваться и управляться с помощью Transact-SQL при использовании управляемого экземпляра.

На рисунке в следующей таблице перечислены и сравниваются два подмножества представлений каталога. Для краткости подмножества ограничены именами представлений, которые также содержат строку _event. Подмножества имеют разные префиксы имен, так как поддерживают разные типы ядра СУБД.

Имя в SQL Server и Управляемый экземпляр SQL Azure	Имя в База данных SQL Azure и Управляемый экземпляр SQL Azure
server_event_notifications server_event_session_actions server_event_session_events server_event_session_fields server_event_session_targets server_event_sessions server_events server_trigger_events	database_event_session_actions database_event_session_events database_event_session_fields database_event_session_targets database_event_sessions

Два списка в предыдущей таблице были точными по состоянию на март 2022 года. Для актуального списка выполните следующую инструкцию Transact-SQL SELECT :

SELECT name
    FROM sys.all_objects
    WHERE
        (name LIKE 'database[_]%' OR
         name LIKE 'server[_]%' )
        AND name LIKE '%[_]event%'
        AND type = 'V'
        AND SCHEMA_NAME(schema_id) = 'sys'
    ORDER BY name;

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

CREATE EVENT SESSION (Transact-SQL)

Синтаксис

Аргументы

event_session_name

ADD EVENT [ event_module_guid ].event_package_name.event_name

SET { event_customizable_attribute= <value> [ ,...n] }

ACTION ( { [event_module_guid].event_package_name.action_name [ ,...n] })

WHERE <predicate_expression>

ADD TARGET [event_module_guid].event_package_name.target_name

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

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

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 }

Замечания

Разрешения

Примеры

Пример для SQL Server

Пример SQL Azure

Примеры кода могут отличаться для базы данных SQL Azure и управляемого экземпляра SQL

См. также

Следующие шаги

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

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