ALTER EVENT SESSION (Transact-SQL)

Artigo
03/07/2014

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

Aplica-se a: SQL Server (do SQL Server 2008 à versão atual).

Ícone de vínculo de tópico Convenções da 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, 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.
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 true, o evento será processado mais tarde 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. 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, 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_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> precisa ser válido na sessão do 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.

Importante

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 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> precisa 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.

Dica

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 kilobyte (KB) ou de 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_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.

Dica

Se STARTUP_STATE = ON, a sessão de evento somente iniciará se o SQL Server for parado e reiniciado.

Termo	Definição
ON	A sessão de evento é iniciada na inicialização.
OFF	A 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

Exige 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