ALTER EVENT SESSION (Transact-SQL)

Artigo
05/15/2024

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

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

Argumentos

Termo	Definição
event_session_name	É o nome de uma sessão de evento existente.
STATE = START \| STOP	Inicia ou para a sessão de evento. Este argumento é válido somente quando ALTER EVENT SESSION é aplicado a um objeto de sessão de evento.
ADD EVENT <event_specifier>	Associa o evento identificado por <event_specifier> à sessão de evento.
[event_module_guid] .event_package_name.event_name	É o nome de um evento em um pacote 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 “evento”.
SET { event_customizable_attribute= <value> [ ,...n] }	Especifica atributos personalizáveis do evento. Os atributos personalizáveis são mostrados na exibição sys.dm_xe_object_columns como column_type 'personalizável' e 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 “ação”.
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 processamento de ação e destino não ocorrerá para esse evento. As expressões de predicado são limitadas a 3.000 caracteres, o que limita os argumentos de cadeia de caracteres.
event_field_name	É o nome do campo de evento que identifica a origem do predicado.
[event_module_guid].event_package_name.predicate_source_name	É 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'.
[event_module_guid].event_package_name.predicate_compare_name	É o nome do objeto de predicado 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 predicado. - predicate_compare_name é uma origem global definida na exibição sys.dm_xe_objects como object_type 'pred_compare'.
DROP EVENT <event_specifier>	Remove o evento identificado por <event_specifier>>. <event_specifier> deve ser válido na sessão do evento.
ADD TARGET <event_target_specifier>	Associa o destino identificado por <event_target_specifier> à sessão de evento.
[event_module_guid].event_package_name.target_name	É o nome do destino na 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 é a ação. As ações aparecem na exibição sys.dm_xe_objects como object_type “destino”.
SET { target_parameter_name= <value> [, ...n] }	Define um parâmetro de destino. Os parâmetros de destino são mostrados na exibição sys.dm_xe_object_columns como column_type 'personalizável' e object_name = target_name. Observação: se você usar o destino do buffer de anel, recomendamos que defina o parâmetro de destino max_memory como 2.048 kilobytes (KB) para ajudar a evitar possíveis truncamentos de dados da saída XML. Para obter mais informações sobre como usar os diferentes tipos de destino, consulte Destinos de eventos estendidos do SQL Server.
DROP TARGET <event_target_specifier>	Remove o destino identificado por <event_target_specifier>. <event_target_specifier> deve ser válido na sessão do evento.
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. Isso pode causar problemas de desempenho detectáveis enquanto a sessão de evento está ativa. As conexões de usuário poderão parar enquanto esperam a liberação de eventos do buffer. Para destinos de arquivo de evento no Banco de Dados SQL do Azure, comporta-se da mesma forma que ALLOW_SINGLE_EVENT_LOSS. Para obter mais informações, consulte EVENT_RETENTION_MODE.
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. O valor mínimo de latência é 1 segundo. No entanto, o valor 0 pode ser usado para especificar a latência INFINITE. Por padrão, este valor é definido como 30 segundos. seconds SECONDS O tempo, em segundos, a esperar antes de liberar buffers para os destinos. seconds é um número inteiro. INFINITE Libera buffers para os destinos somente quando eles estão cheios ou quando a sessão de evento é 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 size são criados, além de MAX_MEMORY. Isso significa que a memória total usada para buffer de evento é 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 do 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. Se STARTUP_STATE=ON, a sessão de evento só será iniciada se o SQL Server for interrompido e reiniciado. ON= a sessão de evento é iniciada na inicialização. OFF = A sessão de evento NÃO é iniciada na inicialização.

Comentários

Os ADD argumentos and DROP não podem ser usados na mesma instrução.

Permissões

Requer a permissão ALTER ANY EVENT SESSION.

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

O exemplo a seguir inicia uma sessão de evento, obtém algumas estatísticas de sessão ao vivo e, em seguida, adiciona dois eventos à sessão existente.

-- Start the event session  
ALTER EVENT SESSION test_session ON SERVER  
STATE = start;  
GO  

-- Obtain live session statistics   
SELECT * FROM sys.dm_xe_sessions;  
SELECT * FROM sys.dm_xe_session_events;  
GO  
  
-- Add new events to the session  
ALTER EVENT SESSION test_session ON SERVER  
ADD EVENT sqlserver.database_transaction_begin,  
ADD EVENT sqlserver.database_transaction_end;  
GO

Partilhar via

ALTER EVENT SESSION (Transact-SQL)

Sintaxe

Argumentos

Comentários

Permissões

Exemplos

Confira também

Comentários

Recursos adicionais