ALTER EVENT SESSION (Transact-SQL)

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

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

Convenções de sintaxe de Transact-SQL

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

Observação

Para exibir a sintaxe do Transact-SQL para o SQL Server 2014 (12.x) e versões anteriores, confira a Documentação das versões anteriores.

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 falsa, o evento será removido pela sessão antes de ser processado pelas ações e pelos destinos da sessão. 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ê estiver usando o destino de buffer de anel, recomendamos definir o parâmetro de destino max_memory como 2.048 KB (kilobytes) para ajudar a evitar um possível truncamento 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 sejam 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.
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 deverá ser definido apenas para permitir eventos únicos maiores que MAX_MEMORY; sua definição como menos que MAX_MEMORY irá gerar 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 iniciará somente se o SQL Server for parado e depois reinicializado.

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 argumentos ADD e DROP não podem ser usados na mesma instrução.

Permissões

Requer a permissão ALTER ANY EVENT SESSION.

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  

Consulte Também

CREATE EVENT SESSION (Transact-SQL)
DROP EVENT SESSION (Transact-SQL)
Destinos de eventos estendidos do SQL Server
sys.server_event_sessions (Transact-SQL)
sys.dm_xe_objects (Transact-SQL)
sys.dm_xe_object_columns (Transact-SQL)