CREATE EVENT SESSION (Transact-SQL)

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

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

Соглашения о синтаксисе Transact-SQL

Синтаксис

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

Дополнительные сведения о типах целевых объектов см. в разделе "Целевые объекты для расширенных событий" в 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 может вызвать обнаруженные проблемы с производительностью во время активного сеанса событий. Соединения пользователя могут простаивать при ожидании событий, данные которых должны быть записаны на диск из буфера.

MAX_DISPATCH_LATENCY = { seconds SECONDS | INFINITE }

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

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

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.

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

В следующем примере демонстрируется, как создать сеанс событий с именем 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: узел Расширенные события, содержащий все сеансы на уровне сервера, отображается в папке Управление для каждого управляемого экземпляра в обозревателе объектов.

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

Два списка в предыдущей таблице были точными по состоянию на март 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;

См. также

• sys.server_event_sessions (Transact-SQL)
• sys.dm_xe_objects (Transact-SQL)
• sys.dm_xe_object_columns (Transact-SQL)

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

• ALTER EVENT SESSION (Transact-SQL)
• DROP EVENT SESSION (Transact-SQL)