CREATE EVENT SESSION (Transact-SQL)

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

Convenções de 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.

  Os eventos aparecem na exibição sys.dm_xe_objects como object_type 'event'.

• SET { event_customizable_attribute = <value> [ ,...n] }
  Permite atributos personalizáveis para o evento a ser definido. Os atributos personalizáveis aparecem na exibição sys.dm_xe_object_columns como column_type 'customizable' 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.

  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 falso, o evento será cancelado 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 é 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. Os destinos aparecem na exibição sys.dm_xe_objects como object_type 'target'.

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

• 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 quilobytes (KB) ou megabytes (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 estiverem 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, entretanto, uma grande quantidade de eventos da sessão poderá ser perdida .

  • 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 começar a enviar buffers aos 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çã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 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.

  • NONE
    Um único conjunto de buffers é criado na instância do SQL Server.

  • PER_NODE
    Um conjunto de buffers é criado para cada nó NUMA. Para obter mais informações, consulte Compreendendo o Non-uniform Memory Access.

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

Requer a permissão CONTROL SERVER.

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

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] }.

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)