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

Примечание.

Сведения о синтаксисе Transact-SQL для SQL Server 2014 (12.x) и более ранних версиях см . в документации по предыдущим версиям.

Аргументы

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

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

Примечание.

Для управляемых экземпляров рекомендуется использовать сеансы на уровне сервера. Сеансы область базы данных не отображаются в обозреватель объектов в 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;

См. также

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