ALTER EVENT SESSION (Transact-SQL)
Inicia ou pára 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 interrompe 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> com a sessão de evento. |
[event_module_guid].event_package_name.event_name |
É o nome de um evento em um pacote de evento, onde:
Os eventos aparecem na exibição sys.dm_xe_objects como object_type 'event'. |
SET { event_customizable_attribute = <value> [ ,...n] } |
Especifica atributos personalizáveis para o evento. Os atributos personalizáveis aparecem 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:
As ações aparecem na exibição sys.dm_xe_objects como object_type 'action'. |
WHERE <predicate_expression> |
Especifica a expressão de predicado usada para determinar se um evento deve ser processado. Se <predicate_expression> for true, o evento será processado ainda mais pelas ações e pelos destinos da sessão. Se <predicate_expression> for false, o evento será descartado pela sessão antes de ser processado pelas ações e pelos destinos da sessão. Expressões de predicado são limitadas a 3000 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].event_package_name.predicate_compare_name |
É o nome do objeto de predicado a ser associado à sessão de evento, onde:
|
DROP EVENT <event_specifier> |
Descarta o evento identificado por <event_specifier>. <event_specifier> deve ser válido na sessão de evento. |
ADD TARGET <event_target_specifier> |
Associa o destino identificado por <event_target_specifier> com a sessão de evento. |
[event_module_guid].event_package_name.target_name |
É o nome do destino na sessão de evento, onde:
|
SET { target_parameter_name = <value> [, ...n] } |
Define um parâmetro de destino. Os parâmetros de destino aparecem na exibição sys.dm_xe_object_columns como column_type 'customizable' e object_name = target_name.
Importante
Se você estiver usando o destino de buffer de anel, é recomendável definir o parâmetro de destino max_memory como 2048 quilobytes (KB) para ajudar a evitar um possível truncamento de dados da saída XML. Para obter mais informações sobre quando usar os diferentes tipos de assinatura, consulte Destinos de eventos estendidos do SQL Server.
|
DROP TARGET <event_target_specifier> |
Descarta o destino identificado por <event_target_specifier>. <event_target_specifier> deve ser válido na sessão de 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.
|
MAX_DISPATCH_LATENCY = { seconds SECONDS | INFINITE } |
Especifica o tempo em que os eventos ficarão armazenados no buffer de memória antes de serem 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.
|
MAX_EVENT_SIZE = size [ KB | MB ] |
Especifica o tamanho máximo permitido para eventos. MAX_EVENT_SIZE deverá ser definido somente 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 em quilobytes (KB) ou megabytes (MB). Se size for especificado em quilobytes, o tamanho mínimo permitido será 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 os buffers de evento são criados.
PER_NODEUm conjunto de buffers é criado para cada nó NUMA. Para obter mais informações, consulte Compreendendo o Non-uniform Memory Access.
PER_CPUUm conjunto de buffers é criado para cada CPU.
|
TRACK_CAUSALITY ={ ON | OFF } |
Especifica se a causalidade é controlada. Se habilitada, a causalidade permitirá que eventos relacionados em conexões de servidor diferentes sejam correlacionados. |
STARTUP_STATE ={ ON | OFF } |
Especifica se a sessão de evento deve ser iniciada automaticamente quando o SQL Server é iniciado.
Observação
Se STARTUP_STATE = ON, a sessão de evento somente iniciará se o SQL Server for parado e reiniciado.
TermoDefinição
ONA sessão de evento é iniciada na inicialização.
OFFA sessão de evento não é iniciada na inicialização.
|
Comentários
Não podem ser usados os argumentos ADD e DROP na mesma instrução.
Permissões
Requer a permissão CONTROL SERVER.
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
Histórico de alterações
Conteúdo atualizado |
---|
O valor padrão do argumento MAX_DISPATCH_LATENCY foi corrigido. |
Adicionada uma observação importante à descrição de SET { target_parameter_name = <value> [, ...n] }. |