CREATE EVENT SESSION (Transact-SQL)

Применятся к:yesSQL Server (все поддерживаемые версии) YesБаза данных SQL Azure

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

Topic link iconСинтаксические обозначения в 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 и более ранних версий, см. в статье Документация по предыдущим версиям.

Аргументы

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

Задает параметр целевого объекта. Целевые параметры отображаются в представлении sys.dm_xe_object_columns как column_type 'customizable' и object_name = = target_name.

Важно!

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

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

Remarks

Приоритеты выполнения логических операторов распределяются следующим образом: 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, необходимо внести небольшие изменения для их выполнения в облаке. Одна категория таких примеров кода включает системные представления, чьи префиксы имен немного различаются в двух системах баз данных:

  • Префикс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 Имя в облачной службе
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 г. Однако содержимое таблицы может устареть, так как оно не обновляется. Чтобы получить точные списки, выполните приведенную ниже инструкцию T-SQL SELECT.

SELECT name
    FROM sys.all_objects
    WHERE
        (name LIKE 'database\_%' { ESCAPE '\' } OR
         name LIKE 'server\_%' { ESCAPE '\' })
        AND name LIKE '%\_event%' { ESCAPE '\' }
        AND type = 'V'
    ORDER BY name;

См. также раздел

Дальнейшие действия