ALTER SESSÃO DE EVENTOS (Transact-SQL)

Aplica-se a:SQL Server Azure SQL Managed Instance

Inicia ou interrompe uma sessão de evento ou altera uma configuração de sessão de evento.

Sintaxe

ALTER EVENT SESSION event_session_name
ON { SERVER | DATABASE }
{
    [ [ {  <add_drop_event> [ , ...n ] }
       | { <add_drop_event_target> [ , ...n ] } ]
    [ WITH ( <event_session_options> [ , ...n ] ) ]
    ]
    | [ STATE = { START | STOP } ]
}

<add_drop_event>::=
{
    [ ADD EVENT <event_specifier>
         [ ( {
                 [ SET { event_customizable_attribute = <value> [ , ...n ] } ]
                 [ ACTION ( { [event_module_guid].event_package_name.action_name [ , ...n ] } ) ]
                 [ WHERE <predicate_expression> ]
        } ) ]
   ]
   | DROP EVENT <event_specifier> }

<event_specifier> ::=
{
[event_module_guid].event_package_name.event_name
}
<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'
}

<add_drop_event_target>::=
{
    ADD TARGET <event_target_specifier>
        [ ( SET { target_parameter_name = <value> [ , ...n ] } ) ]
    | DROP TARGET <event_target_specifier>
}

<event_target_specifier>::=
{
    [event_module_guid].event_package_name.target_name
}

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

Arguments

event_session_name

O nome de uma sessão de evento existente.

ESTADO = INÍCIO | PARAR

Inicia ou interrompe a sessão do evento. O STATE argumento deve ser especificado por si só. Não pode ser combinado com quaisquer outros argumentos na mesma ALTER EVENT SESSION declaração.

ADICIONAR event_specifier EVENTO <>

Identifica um evento a ser associado à sessão do evento. < > event_specifier é na forma de [event_module_guid].event_package_name. event_name, 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 = <valor> [ ,... 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;

AÇÃO ( { [event_module_guid].event_package_name. action_name [ ,... n ] })

A ação a associar ao evento, onde:

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 verdadeiro, o evento será processado posteriormente pelas ações e destinos da sessão. Se <predicate_expression> for falso, 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 fonte 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 origem do predicado.
predicate_source_name é o nome da fonte do predicado.

As fontes de predicados 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 predicados, onde:

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 predicados.
predicate_compare_name é o nome do comparador de predicados.

Os comparadores de predicados 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;

number

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 predicados. Nenhuma conversão implícita de tipo de cadeia de caracteres é executada para as funções de comparação de predicados. Passar o valor de um tipo inesperado resulta em um erro.

DROP EVENTO <event_specifier>

Identifica um evento a ser removido da sessão do evento. O especificador de eventos está na forma de [event_module_guid]. event_package_name. event_name, 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 action.
event_name é o objeto do evento.

< > event_specifier deve identificar um evento que foi adicionado anteriormente à sessão do evento.

ADICIONAR event_target_specifier DE DESTINO <>

Identifica um destino a ser associado a uma sessão de evento. O especificador de destino de evento está na forma de [event_module_guid]. event_package_name. target_name, 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 action.
target_name é o nome do alvo.

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, não é possível 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 = <valor> [ , ... 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 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-placeholder';

Importante

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

Para obter mais informações sobre tipos de destino, consulte Destinos de eventos estendidos.

LANÇAR <ALVO event_target_specifier>

Identifica um destino a ser removido de uma sessão de evento. O especificador de destino de evento está na forma de [event_module_guid]. event_package_name. target_name, 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 action.
target_name é o nome do alvo.

O especificador de destino de evento deve identificar um destino que foi adicionado anteriormente à sessão de evento.

COM ( <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 para a sessão para buffer de eventos. O padrão é 4 MB. tamanho é um número inteiro e pode ser um valor de kilobyte (KB) ou megabyte (MB). O valor máximo não pode exceder 2 GB (2.048 MB). No entanto, o uso de valores de memória no intervalo de GB não é recomendado.

EVENT_RETENTION_MODE = { ALLOW_SINGLE_EVENT_LOSS | ALLOW_MULTIPLE_EVENT_LOSS | NO_EVENT_LOSS }

Especifica o modo de retenção de eventos a ser usado para lidar com a perda de eventos.

ALLOW_SINGLE_EVENT_LOSS

Um evento pode ser perdido da sessão. Um único evento só é descartado quando todos os buffers de eventos estão cheios. A perda de um único evento quando os buffers de eventos estão cheios minimiza o impacto no desempenho e, ao mesmo tempo, minimiza a perda de dados no fluxo de eventos processado.
ALLOW_MULTIPLE_EVENT_LOSS

Buffers de eventos completos contendo vários eventos podem ser perdidos da sessão. O número de eventos perdidos depende do tamanho da memória alocada para a sessão, do particionamento da memória e do tamanho dos eventos no buffer. Essa opção geralmente evita o impacto no desempenho do 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. Esta opção garante que todos os eventos gerados sejam mantidos. O uso dessa opção força todas as tarefas que disparam eventos a aguardar até que o espaço esteja disponível em um buffer de eventos. O uso do NO_EVENT_LOSS pode causar problemas de desempenho detetáveis enquanto a sessão do evento estiver ativa. As sessões e consultas do usuário podem parar enquanto aguardam que os eventos sejam liberados do buffer.

Observação

Para os destinos de arquivo de evento no Banco de Dados SQL do Azure e na Instância Gerenciada SQL do Azure (com a política de atualizaçãoSQL Server 2025 ou Always-up-to-date), a partir de junho de 2024, NO_EVENT_LOSS comporta-se da mesma forma que ALLOW_SINGLE_EVENT_LOSS. Se você especificar NO_EVENT_LOSS, um aviso com ID de mensagem 25665, gravidade 10 e mensagem This target doesn't support the NO_EVENT_LOSS event retention mode. The ALLOW_SINGLE_EVENT_LOSS retention mode is used instead. será retornado 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 usado com destinos de arquivo de evento no armazenamento de blob do Azure.

NO_EVENT_LOSS está planeada para remoção como um argumento suportado EVENT_RETENTION_MODE em futuras atualizações da Base de Dados SQL do Azure e da Instância Gerida SQL do Azure. Evite usar esse recurso em novos trabalhos de desenvolvimento e planeje modificar aplicativos que atualmente usam esse recurso.

MAX_DISPATCH_LATENCY = { segundos SEGUNDOS | INFINITO }

Especifica a quantidade de tempo que os eventos são armazenados em buffer na memória antes de serem enviados para destinos de sessão de eventos. Por padrão, esse valor é definido como 30 segundos.

segundos SEGUNDOS

O tempo, em segundos, para esperar antes de começar a liberar buffers para os alvos. segundos é um número inteiro. O valor mínimo de latência é de 1 segundo. No entanto, 0 pode ser usado para especificar latência INFINITA.
INFINITO

Libere buffers para destinos somente quando os buffers estiverem cheios ou quando a sessão de eventos for fechada.

MAX_EVENT_SIZE = tamanho [ KB | MB ]

Especifica o tamanho máximo permitido para eventos. MAX_EVENT_SIZE só deve ser definido para permitir eventos individuais maiores que MAX_MEMORY; defini-lo como inferior a MAX_MEMORY gera um erro. tamanho é um número inteiro e pode ser um valor de kilobyte (KB) ou megabyte (MB). Se o tamanho for especificado em kilobytes, o tamanho mínimo permitido é 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 dos buffers de eventos. Opções diferentes resultam NONE em mais buffers e maior consumo de memória, mas podem evitar contenção e melhorar o desempenho em máquinas 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 = { ATIVADO | DESLIGADO }

Especifica se a causalidade do evento é rastreada ou não. Se habilitada, a causalidade permite que eventos relacionados em diferentes conexões de servidor sejam correlacionados.

STARTUP_STATE = { EM | DESLIGADO }

Especifica se essa sessão de evento deve ou não ser iniciada automaticamente quando o Mecanismo de Banco de Dados for iniciado.

Observação

Se STARTUP_STATE = ON, a sessão de eventos será iniciada quando o Mecanismo de Banco de Dados for interrompido e, em seguida, reiniciado. Para iniciar a sessão do evento imediatamente, use ALTER EVENT SESSION ... ON SERVER STATE = STARTo .

ON

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

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

MAX_DURATION = { duração do tempo { SEGUNDOS | ATAS | HORÁRIO | DIAS } | ILIMITADO }

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

ILIMITADO

Faz com que uma sessão de evento seja executada indefinidamente uma vez iniciada, até parar de usar a ALTER EVENT SESSION ... STATE = STOP instrução.
Duração do tempo SEGUNDOS | ATAS | HORÁRIO | DIAS

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

Para obter mais informações, consulte Sessões de eventos com limite de tempo.

Observações

Para obter mais informações sobre argumentos de sessão de evento, consulte Sessões de eventos estendidos.

Os ADD argumentos e DROP não podem ser usados na mesma declaração.

Permissions

O SQL Server e a Instância Gerenciada SQL do Azure exigem a ALTER ANY EVENT SESSION permissão.

O Banco de Dados SQL do Azure requer a ALTER ANY DATABASE EVENT SESSION permissão no banco de dados.

Sugestão

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 Azure SQL para melhorar a aderência com PoLP.

Examples

A. Iniciar e parar uma sessão de evento

Para usar este exemplo com sessões de eventos de banco de dados, substitua ON SERVER por ON DATABASE.

ALTER EVENT SESSION test_session ON SERVER STATE = START;
ALTER EVENT SESSION test_session ON SERVER STATE = STOP;

B. Adicionar novos eventos a uma sessão existente