CREATE EVENT SESSION (Transact-SQL)

Aplica-se a: SQL Server Banco de Dados SQL do Azure Instância Gerenciada de SQL do Azure

Cria uma sessão de Eventos Estendidos que identifica a origem dos eventos, os destinos da sessão de evento e as opções da sessão de evento.

Convenções de sintaxe de Transact-SQL

Sintaxe

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

Argumentos

event_session_name

É o nome definido pelo usuário para a sessão de evento. event_session_name é alfanumérico, pode ter até 128 caracteres, deve ser exclusivo em uma instância do SQL Server e deve obedecer às regras de Identificadores.

ADD EVENT [ event_module_guid ].event_package_name.event_name

É o evento a ser associado com a sessão de evento, onde:

• event_module_guid é o GUID do módulo que contém o evento.
• event_package_name é o pacote que contém o objeto de ação.
• event_name é o objeto de evento.

Eventos aparecem na exibição sys.dm_xe_objects como object_type 'event'.

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

Permite atributos personalizáveis para o evento a ser definido. Os atributos personalizáveis são mostrados na exibição sys.dm_xe_object_columns como column_type 'customizable ' and object_name = event_name.

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

É a ação a ser associada à sessão de evento, onde:

• event_module_guid é o GUID do módulo que contém o evento.
• event_package_name é o pacote que contém o objeto de ação.
• action_name é o objeto de ação.

Ações aparecem na exibição sys.dm_xe_objects como object_type 'action'.

WHERE <predicate_expression>

Especifica a expressão de predicado usada para determinar se um evento deve ser processado. Se <predicate_expression> for verdadeira, o evento será processado mais detalhadamente pelas ações e pelos destinos da sessão. Se <predicate_expression> for false, o evento será descartado, evitando ação adicional e processamento de destino. As expressões de predicado são limitadas a 3.000 caracteres.

nome_do_campo_de_evento O nome do campo de evento que identifica a origem do predicado.

[guid_do_módulo_de_evento].nome_do_pacote_de_evento.nome_da_origem_de_predicado O nome da origem do predicado global, onde:

• event_module_guid é o GUID do módulo que contém o evento.
• event_package_name é o pacote que contém o objeto de predicado.
• predicate_source_name é definido na exibição sys.dm_xe_objects como object_type 'pred_source'.

[guid_do_módulo_de_evento].nome_do_pacote_de_evento.nome_da_comparação_de_predicado O nome do objeto predicado a associar ao evento, onde:

• event_module_guid é o GUID do módulo que contém o evento.
• event_package_name é o pacote que contém o objeto de predicado.
• predicate_compare_name é uma origem global definida na exibição sys.dm_xe_objects como object_type 'pred_compare'.

número é qualquer tipo numérico, incluindo decimal. Limitações são a falta de memória física disponível ou um número que é muito grande para ser representado como um inteiro de 64 bits.

'cadeia de caracteres' Uma cadeia de caracteres ANSI ou Unicode, conforme requerido pela comparação de predicado. Nenhuma conversão de tipo de cadeia de caracteres implícita é executada para as funções de comparação de predicado. A transferência do tipo incorreto resulta em um erro.

ADD TARGET [event_module_guid].event_package_name.target_name

É o destino a ser associado à sessão de evento, onde:

• event_module_guid é o GUID do módulo que contém o evento.
• event_package_name é o pacote que contém o objeto de ação.
• target_name é o destino. Destinos aparecem na exibição sys.dm_xe_objects como object_type 'target'.

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

Define um parâmetro de destino.

Para ver todos os parâmetros de destino e suas descrições, execute a consulta a seguir, substituindo o espaço reservado target-name pelo nome do destino, como event_file, ring_buffer, histogram, etc.

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

Importante

Se você estiver usando o destino do buffer de anel, recomendamos que você defina o MAX_MEMORY parâmetro de destino (distinto do MAX_MEMORY parâmetro session) como 1024 kilobytes (KB) ou menos para ajudar a evitar possíveis truncamentos de dados da saída XML.

Para obter mais informações sobre tipos de destino, consulte Destinos para Eventos Estendidos no SQL Server.

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

Especifica as opções a serem usadas com a sessão de evento.

MAX_MEMORY =size [ KB | MB ]

Especifica a quantidade máxima de memória a ser alocada à sessão para buffer de evento. O padrão é 4 MB. size é um número inteiro e pode ser um valor kilobyte (KB) ou megabyte (MB). A quantidade máxima não pode exceder 2 GB (menos de 2.048 MB). No entanto, não é recomendável usar valores de memória no intervalo de GB.

EVENT_RETENTION_MODE = { ALLOW_SINGLE_EVENT_LOSS | ALLOW_MULTIPLE_EVENT_LOSS | NO_EVENT_LOSS }

Especifica o modo de retenção do evento para usar em tratamento de perda de evento.

ALLOW_SINGLE_EVENT_LOSS Um evento pode ser perdido da sessão. Um único evento será descartado somente quando todos os buffers de evento estiverem cheios. A perda de um único evento quando os buffers de evento estão cheios permite características de desempenho do SQL Server aceitáveis, enquanto minimiza a perda de dados no fluxo de evento processado.

ALLOW_MULTIPLE_EVENT_LOSS Buffers de evento cheios que contêm vários eventos podem ser perdidos da sessão. O número de eventos perdidos depende do tamanho de memória alocado à sessão, do particionamento da memória e do tamanho dos eventos no buffer. Essa opção minimiza o impacto do desempenho no servidor quando buffers de evento são rapidamente enchidos, mas grandes números de eventos podem ser perdidos da sessão.

NO_EVENT_LOSS Nenhuma perda de evento é permitida. Essa opção assegura que todos os eventos gerados serão retidos. O uso dessa opção força todas as tarefas que acionam eventos a esperar até que haja espaço disponível em um buffer de evento. O uso de NO_EVENT_LOSS pode causar problemas de desempenho detectáveis enquanto a sessão de eventos está ativa. As conexões de usuário poderão parar enquanto esperam a liberação de eventos do buffer.

Observação

Para os destinos de arquivo de evento no Banco de Dados SQL do Azure e na Instância Gerenciada de SQL do Azure com a política de atualização sempre atualizada, a partir de junho de 2024, NO_EVENT_LOSS se comporta da mesma forma que ALLOW_SINGLE_EVENT_LOSS. Se você especificar NO_EVENT_LOSS, um aviso com a ID de mensagem 25665, gravidade 10 e mensagem Esse destino não dá suporte ao modo de retenção de eventos NO_EVENT_LOSS. Em vez disso, o modo de retenção ALLOW_SINGLE_EVENT_LOSS é usado. é retornado e a sessão é criada.

Essa alteração evita tempos limite de conexão, atrasos de failover e outros problemas que podem reduzir a disponibilidade do banco de dados quando NO_EVENT_LOSS é usado com destinos de arquivo de evento no armazenamento de blobs do Azure.

NO_EVENT_LOSS será removido como um argumento de EVENT_RETENTION_MODE com suporte em atualizações futuras para o Banco de Dados SQL do Azure e a Instância Gerenciada de SQL do Azure. Evite usar esse recurso em desenvolvimentos novos e planeje modificar os aplicativos que atualmente o utilizam.

MAX_DISPATCH_LATENCY = { seconds SECONDS | INFINITE }

Especifica a quantidade de tempo em que os eventos serão colocados no buffer de memória antes que sejam despachados para destinos de sessão de evento. Por padrão, este valor é definido como 30 segundos.

segundos SECONDS O tempo, em segundos, a esperar antes de liberar buffers para os destinos. seconds é um número inteiro. O valor mínimo de latência é 1 segundo. No entanto, o valor 0 pode ser usado para especificar a latência INFINITE.

INFINITE Libera buffers para os destinos somente quando estiverem cheios ou quando a sessão de evento for fechada.

Observação

MAX_DISPATCH_LATENCY = 0 SECONDS é equivalente a MAX_DISPATCH_LATENCY = INFINITE.

MAX_EVENT_SIZE =size [ KB | MB ]

Especifica o tamanho máximo permitido para eventos. MAX_EVENT_SIZE só devem ser definidas para permitir eventos únicos maiores que MAX_MEMORY; defini-lo como menor que MAX_MEMORY gera um erro. size é um número inteiro e pode ser um valor de KB (kilobyte) ou MB (megabyte). Se size for especificado em kilobytes, o tamanho mínimo permitido será de 64 KB. Quando MAX_EVENT_SIZE é definido, dois buffers de tamanho são criados além de MAX_MEMORY e a memória total usada para buffer de eventos é MAX_MEMORY + 2 * MAX_EVENT_SIZE.

MEMORY_PARTITION_MODE = { NONE | PER_NODE | PER_CPU }

Especifica o local onde buffers de evento são criados.

NONE Um único conjunto de buffers é criado na instância SQL Server.

PER NODE Um conjunto de buffers é criado para cada nó NUMA.

PER CPU Um conjunto de buffers é criado para cada CPU.

TRACK_CAUSALITY = { ON | OFF }

Especifica se a causalidade deve ou não ser controlada. Se habilitada, a causalidade permitirá que eventos relacionados em conexões de servidor diferentes sejam correlacionados.

STARTUP_STATE = { ON | OFF }

Especifica se essa sessão de evento deve ser iniciada automaticamente quando o SQL Server inicia.

Observação

Se STARTUP_STATE = ON, a sessão de evento somente será iniciada se o SQL Server for parado e, em seguida, reiniciado.

ON a sessão de evento é iniciada na inicialização.

OFF A sessão do evento não é iniciada na inicialização.

Comentários

A ordem de precedência para operadores lógicos é NOT (mais alto), seguido por AND, seguido por OR.

Permissões

No SQL Server e na Instância Gerenciada de SQL, requer a permissão (introduzida CREATE ANY EVENT SESSION no SQL Server 2022) ou ALTER ANY EVENT SESSION .

No Banco de Dados SQL, requer a permissão ALTER ANY DATABASE EVENT SESSION no banco de dados.

Dica

O SQL Server 2022 introduziu várias novas permissões mais granulares para Eventos Estendidos, para obter mais informações, consulte Blog: Novas permissões granulares para SQL Server 2022 e SQL do Azure para melhorar a adesão ao PoLP.

Exemplos

Exemplo do SQL Server

O exemplo a seguir mostra como criar uma sessão de evento denominada test_session. Esse exemplo adiciona dois eventos e usa o destino Rastreamento de Eventos do 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

Exemplo do SQL do Azure

Na Instância Gerenciada de SQL do Azure ou Banco de Dados SQL do Azure, armazene arquivos .xel no Armazenamento de Blobs do Azure. Você pode usar sys.fn_xe_file_target_read_file para ler em sessões de evento estendidas que você mesmo cria e armazena em Armazenamento de Blobs do Azure. No passo a passo de exemplo, examine o código de destino do Arquivo de Evento para eventos estendidos em Banco de Dados SQL do Azure e Instância Gerenciada de SQL do Azure.

Exemplos de código podem ser diferentes para Banco de Dados SQL do Azure e Instância Gerenciada de SQL

Alguns exemplos de código Transact-SQL escritos para o SQL Server precisam de pequenas alterações para serem executados no Azure. Uma categoria desses exemplos de código envolve exibições de catálogo cujos prefixos de nome diferem dependendo do tipo de mecanismo de banco de dados:

• server_ - prefixo para SQL Server e Instância Gerenciada de SQL do Azure
• database_ - prefixo para Banco de Dados SQL do Azure e Instância Gerenciada de SQL

O Banco de Dados SQL do Azure dá suporte apenas a sessões de eventos com escopo de banco de dados. O SSMS (SQL Server Management Studio) dá suporte completo a sessões de eventos com escopo de banco de dados para o Banco de Dados SQL do Azure: um nó de Eventos Estendidos que contém sessões com escopo de banco de dados aparece em cada banco de dados no Pesquisador de Objetos.

A Instância Gerenciada de SQL do Azure dá suporte a sessões com escopo de banco de dados e de servidor. O SSMS dá suporte total a sessões com escopo de servidor para Instância Gerenciada de SQL: um nó Eventos Estendidos que contém todas as sessões com escopo de servidor aparece na pasta Gerenciamento para cada instância gerenciada no Pesquisador de Objetos.

Observação

As sessões com escopo de servidor são recomendadas para instâncias gerenciadas. As sessões com escopo de banco de dados não são exibidas no Pesquisador de Objetos no SSMS para a Instância Gerenciada de SQL do Azure. As sessões com escopo de banco de dados só podem ser consultadas e gerenciadas com o Transact-SQL ao usar uma instância gerenciada.

Para fins ilustrativos, a tabela a seguir lista e compara dois subconjuntos de exibições de catálogo. Para resumir, os subconjuntos estão restritos aos nomes de exibição que também contêm a cadeia de caracteres _event. Os subconjuntos têm prefixos de nome diferentes porque oferecem suporte a diferentes tipos de mecanismos de banco de dados.

Nome no SQL Server e na Instância Gerenciada de SQL do Azure	Nome no Banco de Dados SQL do Azure e na Instância Gerenciada de SQL do 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

As duas listas na tabela anterior são precisas em março de 2022. Para obter uma lista atualizada, execute a seguinte instrução SELECT do Transact-SQL:

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;

Confira também

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

Próximas etapas

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