CRIAR SESSÃO DE EVENTO (Transact-SQL)

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

Cria uma sessão de Eventos Estendidos que identifica os eventos a serem coletados, os destinos da sessão de evento e as opções de 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 } ]
    [ [ , ] MAX_DURATION = { <time duration> { SECONDS | MINUTES | HOURS | DAYS } | UNLIMITED } ]
}

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 estar em conformidade com as regras para identificadores de banco de dados.

ON { SERVER | BANCO DE DADOS }

Determina se a sessão de evento está no contexto do servidor ou do banco de dados.

Azure SQL Database e SQL Database no Microsoft Fabric exigem DATABASE.

ADICIONAR EVENTO [event_module_guid]. event_package_name. event_name

O evento a ser associado à sessão de evento, em que:

event_module_guid é o GUID do módulo que contém o evento.
event_package_name é o pacote que contém o evento.
event_name é o nome do evento.

Os eventos disponíveis podem ser encontrados executando a seguinte consulta:

SELECT o.name AS event_name,
       o.description AS event_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'event'
ORDER BY event_name ASC;

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

Atributos personalizáveis para o evento.

Atributos personalizáveis para um determinado evento podem ser encontrados executando a seguinte consulta:

SELECT object_name,
       name AS column_name,
       type_name,
       column_value,
       description
FROM sys.dm_xe_object_columns
WHERE object_name = 'event-name-placeholder'
      AND column_type = 'customizable'
ORDER BY column_name ASC;

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

A ação a ser associada ao evento, em que:

event_module_guid é o GUID do módulo que contém a ação.
event_package_name é o pacote que contém a ação.
action_name é o nome da ação.

As ações disponíveis podem ser encontradas executando a seguinte consulta:

SELECT o.name AS action_name,
       o.description AS action_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'action'
ORDER BY action_name ASC;

ONDE <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. Cada expressão de predicado é limitada a 3.000 caracteres.

event_field_name

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

Os campos de um evento podem ser encontrados executando a seguinte consulta:

SELECT oc.name AS field_name,
       oc.type_name AS field_type,
       oc.description AS field_description
FROM sys.dm_xe_objects AS o
INNER JOIN sys.dm_xe_packages AS p
ON o.package_guid = p.guid
INNER JOIN sys.dm_xe_object_columns AS oc
ON o.name = oc.object_name
   AND
   o.package_guid = oc.object_package_guid
WHERE o.object_type = 'event'
      AND
      o.name = 'event-name-placeholder'
      AND
      oc.column_type = 'data'
ORDER BY field_name ASC;

[event_module_guid]. event_package_name. predicate_source_name

O nome da origem do predicado global em que:

event_module_guid é o GUID do módulo que contém o evento.
event_package_name é o pacote que contém o objeto de origem do predicado.
predicate_source_name é o nome da origem do predicado.

As fontes de predicado podem ser encontradas executando a seguinte consulta:

SELECT o.name AS predicate_source_name,
       o.description AS predicate_source_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'pred_source'
ORDER BY predicate_source ASC;

[event_module_guid].event_package_name.predicate_compare_name

O nome do objeto comparador de predicado, em que:

event_module_guid é o GUID do módulo que contém o evento.
event_package_name é o pacote que contém o objeto comparador de predicado.
predicate_compare_name é o nome do comparador de predicado.

Comparadores de predicado podem ser encontrados executando a seguinte consulta:

SELECT o.name AS predicate_comparator_name,
       o.description AS predicate_comparator_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'pred_compare'
ORDER BY predicate_comparator ASC;

número

Qualquer tipo numérico que possa ser representado como um inteiro de 64 bits.

'string'

Uma cadeia de caracteres ANSI ou Unicode, conforme exigido pelo comparador de predicado. Nenhuma conversão de tipo de cadeia de caracteres implícita é executada para as funções de comparação de predicado. Passar o valor de um tipo inesperado resulta em um erro.

ADICIONAR DESTINO [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 destino.
event_package_name é o pacote que contém o destino.
target_name é o nome de destino.

Os destinos disponíveis podem ser encontrados executando a seguinte consulta:

SELECT o.name AS target_name,
       o.description AS target_description,
       o.capabilities_desc,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'target'
ORDER BY target_name ASC;

Uma sessão de evento pode ter zero, um ou muitos destinos. Todos os destinos adicionados a uma sessão de evento devem ser diferentes. Por exemplo, você não pode adicionar um segundo event_file destino a uma sessão que já tenha um event_file destino.

Para obter mais informações, incluindo exemplos de uso para destinos comumente usados, consulte destinos de Eventos Estendidos.

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 seguinte consulta, substituindo target-name-placeholder pelo nome de destino, como event_file, , ring_buffer, histogrametc.:

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

Importante

Se você estiver usando o destino do buffer de anel, recomendamos definir o MAX_MEMORY parâmetro de destino (distinto do parâmetro de MAX_MEMORYsessão) para 1.024 quilobytes (KB) ou menos para ajudar a evitar possíveis truncamento de dados da saída XML.

Para obter mais informações sobre tipos de destino, consulte os destinos de Eventos Estendidos.

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

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

MAX_MEMORY = tamanho [ 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 (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. Perder um único evento quando os buffers de eventos estiverem completos minimiza o impacto no desempenho, minimizando também a perda de dados no fluxo de eventos 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 geralmente evita o impacto no desempenho no servidor quando os buffers de eventos são preenchidos rapidamente, mas um grande número de eventos pode ser perdido 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 sessões e consultas do usuário podem parar enquanto aguardam a liberação de eventos do buffer.

Observação

Para os alvos de arquivos de eventos no Azure SQL Database, SQL database no Microsoft Fabric e Azure SQL Managed Instance (com a política de atualização SQL Server 2025 ou Always-up-to-date), 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 da mensagem 25665, a severidade 10 e a mensagem This target doesn't support the NO_EVENT_LOSS event retention mode. The ALLOW_SINGLE_EVENT_LOSS retention mode is used instead. serão retornados e a sessão será 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 usados com destinos de arquivo de evento no armazenamento de blobs do Azure.

NO_EVENT_LOSS está planejado para remoção como argumento apoiado EVENT_RETENTION_MODE em futuras atualizações do Azure SQL Database, SQL Database no Microsoft Fabric e Azure SQL Managed Instance. Evite usar esse recurso em desenvolvimentos novos e planeje modificar os aplicativos que atualmente o utilizam.

MAX_DISPATCH_LATENCY = { segundos SEGUNDOS | 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.

SegundosSECONDS

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.
INFINITO

Libera buffers para os destinos somente quando eles estão cheios ou quando a sessão de evento é fechada.

MAX_EVENT_SIZE = tamanho [ 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 = { NENHUM | PER_NODE | PER_CPU }

Especifica a afinidade de buffers de eventos. Opções diferentes de NONE resultar em mais buffers e maior consumo de memória, mas podem evitar contenção e melhorar o desempenho em computadores maiores.

NENHUM

Um único conjunto de buffers é criado na instância do Mecanismo de Banco de Dados.
PER_NODE

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

Um conjunto de buffers é criado para cada CPU.

TRACK_CAUSALITY = { ON | DESLIGADO }

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

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

Observação

Se STARTUP_STATE = ONa sessão de evento for iniciada quando o Mecanismo de Banco de Dados for interrompido e reiniciado. Para iniciar a sessão de evento imediatamente, use ALTER EVENT SESSION ... ON SERVER STATE = START.

ATIVADO

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

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

MAX_DURATION = { duração do tempo { SECONDS | MINUTOS | HORAS | DAYS } | UNLIMITED }

Aplica-se a: SQL Server 2025 (17.x)

ILIMITADO

Cria uma sessão de evento que é executada indefinidamente uma vez iniciada, até parar de usar a ALTER EVENT SESSION ... STATE = STOP instrução. Esse é o padrão se MAX_DURATION não for especificado.
duração do tempo SEGUNDOS | MINUTOS | HORAS | DIAS

Cria uma sessão de evento que é interrompida automaticamente após o tempo especificado ser decorrido após o início da sessão. A duração máxima com suporte é de 2.147.483 segundos, ou 35.792 minutos, ou 596 horas, ou 24 dias.

Para obter mais informações, consulte sessões de evento com limite de tempo.

Comentários

Para obter mais informações sobre argumentos de sessão de evento, consulte sessões de Eventos Estendidos.

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

Permissões

O SQL Server e a Instância Gerenciada de SQL do Azure exigem a CREATE ANY EVENT SESSION permissão (introduzida no SQL Server 2022).ALTER ANY EVENT SESSION

Azure SQL Database e SQL Database no Microsoft Fabric exigem a CREATE ANY DATABASE EVENT SESSION permissão no banco de dados.

Dica

O SQL Server 2022 introduziu 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

A. Exemplo do SQL Server e da Instância Gerenciada de SQL do Azure

O exemplo a seguir mostra como criar uma sessão de evento denominada test_session. Este exemplo adiciona dois eventos e usa o event_file destino, limitando o tamanho de cada arquivo a 256 MB e limitando o número retido de arquivos a 10.

IF EXISTS (SELECT 1
           FROM sys.server_event_sessions
           WHERE name = 'test_session')
    DROP EVENT SESSION test_session ON SERVER;

CREATE EVENT SESSION test_session ON SERVER
ADD EVENT sqlserver.rpc_starting,
ADD EVENT sqlserver.sql_batch_starting,
ADD EVENT sqlserver.error_reported
ADD TARGET package0.event_file
    (
    SET filename = N'C:\xe\test_session.xel',
        max_file_size = 256,
        max_rollover_files = 10
    )
WITH (MAX_MEMORY = 4 MB);

B. Exemplos do Banco de Dados SQL do Azure

Por exemplo, passo a passo, examine Criar uma sessão de evento com um destino event_file no Armazenamento do Azure e crie uma sessão de evento com um destino ring_buffer na memória.

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 Banco de Dados SQL do Azure ou no Banco de Dados SQL no Fabric. 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 o Banco de Dados SQL do Azure, o Banco de Dados SQL no Fabric e a Instância Gerenciada de SQL

O Banco de Dados SQL do Azure e o Banco de Dados SQL no Fabric dão suporte apenas a sessões de eventos no escopo do banco de dados. O SSMS (SQL Server Management Studio) dá suporte a sessões de evento 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

Sessões de evento com escopo de servidor são recomendadas para a Instância Gerenciada de SQL do Azure.

As sessões de evento 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. Em uma instância gerenciada de SQL, as sessões de evento com escopo de banco de dados só podem ser consultadas e gerenciadas com o Transact-SQL.

Para fins ilustrativos, a tabela a seguir lista e compara dois subconjuntos de exibições de catálogo. 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, banco de dados SQL no Fabric e Instância Gerenciada de SQL do Azure
`sys.server_event_session_actions` `sys.server_event_session_events` `sys.server_event_session_fields` `sys.server_event_session_targets` `sys.server_event_sessions`	`sys.database_event_session_actions` `sys.database_event_session_events` `sys.database_event_session_fields` `sys.database_event_session_targets` `sys.database_event_sessions`

Comentários

Esta página foi útil?

Last updated on 2025-11-19

Compartilhar via

CRIAR SESSÃO DE EVENTO (Transact-SQL)

Sintaxe

Argumentos

event_session_name

ON { SERVER | BANCO DE DADOS }

ADICIONAR EVENTO [event_module_guid]. event_package_name. event_name

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

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

ONDE <predicate_expression>

event_field_name

[event_module_guid]. event_package_name. predicate_source_name

[event_module_guid].event_package_name.predicate_compare_name

número

'string'

ADICIONAR DESTINO [event_module_guid]. event_package_name. target_name

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

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

MAX_MEMORY = tamanho [ KB | MB ]

EVENT_RETENTION_MODE = { ALLOW_SINGLE_EVENT_LOSS | ALLOW_MULTIPLE_EVENT_LOSS | NO_EVENT_LOSS }

MAX_DISPATCH_LATENCY = { segundos SEGUNDOS | INFINITE }

MAX_EVENT_SIZE = tamanho [ KB | MB ]

MEMORY_PARTITION_MODE = { NENHUM | PER_NODE | PER_CPU }

TRACK_CAUSALITY = { ON | DESLIGADO }

STARTUP_STATE = { ON | DESLIGADO }

MAX_DURATION = { duração do tempo { SECONDS | MINUTOS | HORAS | DAYS } | UNLIMITED }

Comentários

Permissões

Exemplos

A. Exemplo do SQL Server e da Instância Gerenciada de SQL do Azure

B. Exemplos do Banco de Dados SQL do Azure

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

Conteúdo relacionado

Comentários

Recursos adicionais