ALTER EVENT SESSION (Transact-SQL)
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.
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 } ]
}
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