• Artigo

ALTER EVENT SESSION (Transact-SQL)

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

Ícone de vínculo de tópicoConvenções de sintaxe 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> 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:

  • event_module_guid é o GUID do módulo que contém o evento.

  • event_package_name é o pacote que contém o objeto da ação.

  • event_name é o objeto do evento.

Eventos aparecem na exibição sys.dm_xe_objects como 'evento' object_type.'

SET { event_customizable_attribute = <value> [ ,...n] }

Especifica atributos personalizáveis do evento. 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, 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 da ação.

  • action_name é o objeto da ação.

Ações aparecem na exibição sys.dm_xe_objects como 'ação' object_type.'

WHERE <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 mais tarde pelas ações e pelos destinos da sessão. Se <predicate_expression> for falso, o evento será descartado 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 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 é o GUID do módulo que contém o evento.

  • event_package_name é o pacote que contém o objeto do 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, 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 do predicado.

  • predicate_compare_name é uma origem global definida na exibição sys.dm_xe_objects como object_type 'pred_compare'.

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:

  • event_module_guid é o GUID do módulo que contém o evento.

  • event_package_name é o pacote que contém o objeto da ação.

  • target_name é a ação. As ações aparecem na exibição sys.dm_xe_objects como 'destino' object_type.

SET { target_parameter_name = <value> [, ...n] }

Define um parâmetro de destino. Parâmetros de destino aparecem na exibição sys.dm_xe_object_columns como column_type 'personalizável' e object_name = target_name.

Observação importanteImportante
Se você estiver usando o destino de buffer de anel, é recomendável definir o parâmetro de destino max_memory como 2048 KB (quilobytes) 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.

WITH ( <event_session_options> [ ,...n] )

Especifica as opções a serem usadas com a sessão de evento.

MAX_MEMORY= size [ KB | MB ]

Especifica a quantidade máxima de memória a ser alocada à sessão para buffer de evento. O padrão é 4 MB. size é um número inteiro e pode ser um valor em KB (quilobyte) ou MB (megabyte). A memória alocada para os destinos assíncronos está separada deste valor.

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 começar a enviar buffers aos 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çãoObservaçã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 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 kilobyte (KB) ou megabyte (MB). Se size for especificado em kilobytes, o tamanho mínimo permitido será 64 KB. Quando MAX_EVENT_SIZE é definido, dois buffers de size são acrescentados à 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_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çãoObservaçã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