Partilhar via

CREATE EVENT SESSION (Transact-SQL)

  • Artigo

Cria uma sessão de Eventos Estendidos que identifica a origem dos eventos, os destinos da sessão de evento e as opções da sessão de evento.

Ícone de vínculo de tópico Convenções da sintaxe Transact-SQL.

Sintaxe

CREATE EVENT SESSION event_session_name
ON SERVER
{
    <event_definition> [ ,...n]
    [ <event_target_definition> [ ,...n] ]
    [ WITH ( <event_session_options> [ ,...n] ) ]
}
;
 
<event_definition>::=
{
    ADD EVENT [event_module_guid].event_package_name.event_name 
         [ ( { 
                 [ SET { event_customizable_attribute = <value> [ ,...n] } ]
                 [ ACTION ( { [event_module_guid].event_package_name.action_name [ ,...n] } ) ]
                 [ WHERE <predicate_expression> ]
        } ) ]
}
 
<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'
}

<event_target_definition>::=
{
    ADD TARGET [event_module_guid].event_package_name.target_name
        [ ( SET { target_parameter_name = <value> [ ,...n] } ) ]
}

<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

  • event_session_name
    É o nome definido pelo usuário para a sessão de evento. event_session_name é alfanumérico, pode ter até 128 caracteres, deve ser exclusivo dentro de uma instância do SQL Server e deve obedecer às regras para Identificadores.

  • ADD EVENT [ event_module_guid ].event_package_name.event_name
    É o evento a ser associado com a 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.

    • 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] }
    Permite atributos personalizáveis para o evento a ser definido. 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'.

  • number
    É qualquer tipo numérico incluindo decimal. Limitações são a falta de memória física disponível ou um número que é muito grande para ser representado como um inteiro de 64 bits.

  • 'string'
    Uma cadeia de caracteres ANSI ou Unicode, como requerido pela comparação de predicado. Nenhuma conversão de tipo de cadeia de caracteres implícita é executada para as funções de comparação de predicado. A transferência do tipo errado resulta em um erro.

  • ADD TARGET [event_module_guid].event_package_name.target_name
    É o destino 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 da ação.

    • O target_name é o destino. Destinos 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.

  • 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 de kilobyte (KB) ou de megabyte (MB).

  • 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 na sessão. A quantidade 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 haverá buffer de eventos na memória antes que sejam enviados para destinos de sessão de evento. 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. O valor mínimo de latência é 1 segundo. No entanto, o valor 0 pode ser usado para especificar a latência INFINITE.

    • 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 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 os 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.

    ObservaçãoObservação

    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

A ordem de precedência para operadores lógicos é NOT (mais alto), seguido por AND, seguido por OR.

Permissões

Exige a permissão ALTER ANY EVENT SESSION.

Exemplos

O exemplo a seguir mostra como criar uma sessão de evento denominada test_session. Esse exemplo adiciona dois eventos e usa o destino Rastreamento de Eventos do Windows.

IF EXISTS(SELECT * FROM sys.server_event_sessions WHERE name='test_session')
    DROP EVENT session test_session ON SERVER;
GO
CREATE EVENT SESSION test_session
ON SERVER
    ADD EVENT sqlos.async_io_requested,
    ADD EVENT sqlserver.lock_acquired
    ADD TARGET package0.etw_classic_sync_target 
        (SET default_etw_session_logfile_path = N'C:\demo\traces\sqletw.etl' )
    WITH (MAX_MEMORY=4MB, MAX_EVENT_SIZE=4MB);
GO

Consulte também

Referência

ALTER EVENT SESSION (Transact-SQL)

DROP EVENT SESSION (Transact-SQL)

sys.server_event_sessions (Transact-SQL)

sys.dm_xe_objects (Transact-SQL)

sys.dm_xe_object_columns (Transact-SQL)