CREATE EVENT SESSION (Transact-SQL)CREATE EVENT SESSION (Transact-SQL)

ESTE TÓPICO APLICA-SE A:simSQL Server (a partir de 2008)simBanco de Dados SQL do Microsoft AzurenãoAzure SQL Data Warehouse nãoParallel Data Warehouse THIS TOPIC APPLIES TO:yesSQL Server (starting with 2008)yesAzure SQL DatabasenoAzure SQL Data Warehouse noParallel Data Warehouse

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.Creates an Extended Events session that identifies the source of the events, the event session targets, and the event session options.

Ícone de link do tópico convenções de sintaxe Transact-SQL.Topic link icon Transact-SQL Syntax Conventions.

SintaxeSyntax


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

ArgumentosArguments

event_session_nameevent_session_name
É o nome definido pelo usuário para a sessão de evento.Is the user-defined name for the event session. event_session_name é alfanumérico, pode ter até 128 caracteres, deve ser exclusivo dentro de uma instância de SQL ServerSQL Servere deve estar em conformidade com as regras de identificadores.event_session_name is alphanumeric, can be up to 128 characters, must be unique within an instance of SQL ServerSQL Server, and must comply with the rules for Identifiers.

Adicionar o evento [ event_module_guid ]. event_package_name. event_nameADD EVENT [ event_module_guid ].event_package_name.event_name
É o evento a ser associado com a sessão de evento, onde:Is the event to associate with the event session, where:

  • event_module_guid é o GUID para o módulo que contém o evento.event_module_guid is the GUID for the module that contains the event.

  • event_package_name é o pacote que contém o objeto de ação.event_package_name is the package that contains the action object.

  • event_name é o objeto de evento.event_name is the event object.

    Eventos aparecem na exibição sys.dm_xe_objects como object_type “evento”.Events appear in the sys.dm_xe_objects view as object_type 'event'.

    DEFINIR { event_customizable_attribute= <valor > [,... n] }SET { event_customizable_attribute= <value> [ ,...n] }
    Permite atributos personalizáveis para o evento a ser definido.Allows customizable attributes for the event to be set. Atributos personalizáveis aparecem na exibição sys.DM xe_object_columns como column_type "personalizável" e object_name = event_name.Customizable attributes appear in the sys.dm_xe_object_columns view as column_type 'customizable ' and object_name = event_name.

    AÇÃO ({[event_module_guid]. event_package_name. action_name [ ,... n] })ACTION ( { [event_module_guid].event_package_name.action_name [ ,...n] })
    É a ação a ser associada à sessão de evento, onde:Is the action to associate with the event session, where:

  • event_module_guid é o GUID para o módulo que contém o evento.event_module_guid is the GUID for the module that contains the event.

  • event_package_name é o pacote que contém o objeto de ação.event_package_name is the package that contains the action object.

  • action_name é o objeto de ação.action_name is the action object.

    Ações aparecem na exibição sys.dm_xe_objects como object_type “ação”.Actions appear in the sys.dm_xe_objects view as object_type 'action'.

    ONDE <predicate_expression > especifica a expressão de predicado usada para determinar se um evento deve ser processado.WHERE <predicate_expression> Specifies the predicate expression used to determine if an event should be processed. Se <predicate_expression > for true, o evento é processado mais pelas ações e destinos da sessão.If <predicate_expression> is true, the event is processed further by the actions and targets for the session. Se <predicate_expression > for false, o evento será descartado pela sessão antes de ser processada pelas ações e destinos para a sessão.If <predicate_expression> is false, the event is dropped by the session before being processed by the actions and targets for the session. As expressões de predicado são limitadas a 3.000 caracteres, o que limita os argumentos de cadeia de caracteres.Predicate expressions are limited to 3000 characters, which limits string arguments.

    event_field_nameevent_field_name
    É o nome do campo de evento que identifica a origem do predicado.Is the name of the event field that identifies the predicate source.

    [event_module_guid]. event_package_name. predicate_source_name[event_module_guid].event_package_name.predicate_source_name
    É o nome da origem do predicado global onde:Is the name of the global predicate source where:

  • event_module_guid é o GUID para o módulo que contém o evento.event_module_guid is the GUID for the module that contains the event.

  • event_package_name é o pacote que contém o objeto de predicado.event_package_name is the package that contains the predicate object.

  • predicate_source_name é definido na exibição sys.DM xe_objects como object_type 'pred_source'.predicate_source_name is defined in the sys.dm_xe_objects view as object_type 'pred_source'.

    [event_module_guid]. event_package_name. predicate_compare_name[event_module_guid].event_package_name.predicate_compare_name
    É o nome do objeto de predicado a ser associado à sessão de evento, onde:Is the name of the predicate object to associate with the event, where:

  • event_module_guid é o GUID para o módulo que contém o evento.event_module_guid is the GUID for the module that contains the event.

  • event_package_name é o pacote que contém o objeto de predicado.event_package_name is the package that contains the predicate object.

  • predicate_compare_name é uma origem global definida na exibição sys.DM xe_objects como object_type "pred_compare".predicate_compare_name is a global source defined in the sys.dm_xe_objects view as object_type 'pred_compare'.

    numbernumber
    É qualquer tipo numérico, inclusive decimal.Is any numeric type including 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.Limitations are the lack of available physical memory or a number that is too large to be represented as a 64-bit integer.

    'cadeia de caracteres''string'
    Uma cadeia de caracteres ANSI ou Unicode, conforme requerido pela comparação de predicado.Either an ANSI or Unicode string as required by the predicate compare. Nenhuma conversão de tipo de cadeia de caracteres implícita é executada para as funções de comparação de predicado.No implicit string type conversion is performed for the predicate compare functions. A transferência do tipo incorreto resulta em um erro.Passing the wrong type results in an error.

    Adicionar um destino [event_module_guid]. event_package_name. target_nameADD TARGET [event_module_guid].event_package_name.target_name
    É o destino a ser associado à sessão de evento, onde:Is the target to associate with the event session, where:

  • event_module_guid é o GUID para o módulo que contém o evento.event_module_guid is the GUID for the module that contains the event.

  • event_package_name é o pacote que contém o objeto de ação.event_package_name is the package that contains the action object.

  • target_name é o destino.target_name is the target. Os destinos aparecem na exibição sys.dm_xe_objects como object_type ‘destino’.Targets appear in sys.dm_xe_objects view as object_type 'target'.

    DEFINIR { target_parameter_name= <valor > [,... n] }SET { target_parameter_name= <value> [, ...n] }
    Define um parâmetro de destino.Sets a target parameter. Parâmetros de destino aparecem na exibição sys.DM xe_object_columns como column_type "personalizável" e object_name = target_name.Target parameters appear in the sys.dm_xe_object_columns view as column_type 'customizable' and object_name = target_name.

Importante

Se você estiver usando o destino de buffer de anel, é recomendável que você defina o parâmetro de destino max_memory como 2048 KB (Quilobytes) para ajudar a evitar o truncamento de dados de saída XML.If you are using the ring buffer target, we recommend that you set the max_memory target parameter to 2048 kilobytes (KB) to help avoid possible data truncation of the XML output. Para obter mais informações sobre quando usar os diferentes tipos de destino, consulte SQL Server Extended Events Targets.For more information about when to use the different target types, see SQL Server Extended Events Targets.

COM ( <event_session_options > [,... n ]) Especifica opções para usar com a sessão de evento.WITH ( <event_session_options> [ ,...n] ) Specifies options to use with the event session.

MAX_MEMORY =tamanho [KB | MB ]MAX_MEMORY =size [ KB | MB ]
Especifica a quantidade máxima de memória a ser alocada à sessão para buffer de evento.Specifies the maximum amount of memory to allocate to the session for event buffering. O padrão é 4 MB.The default is 4 MB. tamanho é um número inteiro e pode ser um kilobyte (KB) ou um valor de megabytes (MB).size is a whole number and can be a kilobyte (KB) or a megabyte (MB) value.

EVENT_RETENTION_MODE = { ALLOW_SINGLE_EVENT_LOSS | ALLOW_MULTIPLE_EVENT_LOSS | NO_EVENT_LOSS}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.Specifies the event retention mode to use for handling event loss.

ALLOW_SINGLE_EVENT_LOSSALLOW_SINGLE_EVENT_LOSS
Um evento pode ser perdido da sessão.An event can be lost from the session. Um único evento será descartado somente quando todos os buffers de evento estiverem cheios.A single event is only dropped when all the event buffers are full. A perda de um único evento quando os buffers de evento estão cheios permite características de desempenho do SQL ServerSQL Server aceitáveis, enquanto minimiza a perda de dados no fluxo de evento processado.Losing a single event when event buffers are full allows for acceptable SQL ServerSQL Server performance characteristics, while minimizing the loss of data in the processed event stream.

ALLOW_MULTIPLE_EVENT_LOSSALLOW_MULTIPLE_EVENT_LOSS
Buffers de evento cheios que contêm vários eventos podem ser perdidos da sessão.Full event buffers containing multiple events can be lost from the session. 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.The number of events lost is dependant upon the memory size allocated to the session, the partitioning of the memory, and the size of the events in the 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.This option minimizes performance impact on the server when event buffers are quickly filled, but large numbers of events can be lost from the session.

NO_EVENT_LOSSNO_EVENT_LOSS
Nenhuma perda de evento é permitida.No event loss is allowed. Essa opção assegura que todos os eventos gerados sejam retidos.This option ensures that all events raised will be retained. 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.Using this option forces all tasks that fire events to wait until space is available in an event buffer. Isso pode causar problemas de desempenho detectáveis enquanto a sessão de evento está ativa.This may cause detectable performance issues while the event session is active. As conexões de usuário poderão parar enquanto esperam a liberação de eventos do buffer.User connections may stall while waiting for events to be flushed from the buffer.

MAX_DISPATCH_LATENCY = { segundos segundos | Infinito }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.Specifies the amount of time that events will be buffered in memory before being dispatched to event session targets. Por padrão, este valor é definido como 30 segundos.By default, this value is set to 30 seconds.

segundos segundosseconds SECONDS
O tempo, em segundos, a esperar antes de liberar buffers para os destinos.The time, in seconds, to wait before starting to flush buffers to targets. segundos é um número inteiro.seconds is a whole number. O valor mínimo de latência é 1 segundo.The minimum latency value is 1 second. No entanto, o valor 0 pode ser usado para especificar a latência INFINITE.However, 0 can be used to specify INFINITE latency.

INFINITOINFINITE
Libera buffers para os destinos somente quando eles estão cheios ou quando a sessão de evento é fechada.Flush buffers to targets only when the buffers are full, or when the event session closes.

Observação

MAX_DISPATCH_LATENCY = 0 SECONDS é equivalente a MAX_DISPATCH_LATENCY = INFINITE.MAX_DISPATCH_LATENCY = 0 SECONDS is equivalent to MAX_DISPATCH_LATENCY = INFINITE.

MAX_EVENT_SIZE =tamanho [KB | MB ]MAX_EVENT_SIZE =size [ KB | MB ]
Especifica o tamanho máximo permitido para eventos.Specifies the maximum allowable size for events. 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.MAX_EVENT_SIZE should only be set to allow single events larger than MAX_MEMORY; setting it to less than MAX_MEMORY will raise an error. tamanho é um número inteiro e pode ser um kilobyte (KB) ou um valor de megabytes (MB).size is a whole number and can be a kilobyte (KB) or a megabyte (MB) value. Se tamanho é especificado em kilobytes, o tamanho mínimo permitido é de 64 KB.If size is specified in kilobytes, the minimum allowable size is 64 KB. Quando MAX_EVENT_SIZE é definido, dois buffers de tamanho são à max_memory.When MAX_EVENT_SIZE is set, two buffers of size are created in addition to MAX_MEMORY. Isso significa que a memória total usada para buffer de evento é MAX_MEMORY + 2 * MAX_EVENT_SIZE.This means that the total memory used for event buffering is MAX_MEMORY + 2 * MAX_EVENT_SIZE.

MEMORY_PARTITION_MODE = { NONE | PER_NODE | PER_CPU}MEMORY_PARTITION_MODE = { NONE | PER_NODE | PER_CPU }
Especifica o local onde buffers de evento são criados.Specifies the location where event buffers are created.

NONENONE
Um único conjunto de buffers é criado na instância do SQL ServerSQL Server.A single set of buffers are created within the SQL ServerSQL Server instance.

PER_NODEPER_NODE
Um conjunto de buffers é criado para cada nó NUMA.A set of buffers are created for each NUMA node.

PER_CPUPER_CPU
Um conjunto de buffers é criado para cada CPU.A set of buffers are created for each CPU.

TRACK_CAUSALITY = {ON | OFF }TRACK_CAUSALITY = { ON | OFF }
Especifica se a causalidade deve ou não ser controlada.Specifies whether or not causality is tracked. Se habilitada, a causalidade permitirá que eventos relacionados em conexões de servidor diferentes sejam correlacionados.If enabled, causality allows related events on different server connections to be correlated together.

STARTUP_STATE = {ON | OFF }STARTUP_STATE = { ON | OFF }
Especifica se essa sessão de evento deve ser iniciada automaticamente quando o SQL ServerSQL Server inicia.Specifies whether or not to start this event session automatically when SQL ServerSQL Server starts.

Observação

Se STARTUP_STATE = ON, a sessão de evento iniciará somente se o SQL Server for parado e depois reinicializado.If STARTUP_STATE = ON, the event session will only start if SQL Server is stopped and then restarted.

ONON
A sessão de evento é iniciada na inicialização.The event session is started at startup.

OFFOFF
A sessão de evento não é iniciada na inicialização.The event session is not started at startup.

ComentáriosRemarks

A ordem de precedência para operadores lógicos é NOT (mais alto), seguido por AND, seguido por OR.The order of precedence for the logical operators is NOT (highest), followed by AND, followed by OR.

PermissõesPermissions

Exige a permissão ALTER ANY EVENT SESSION.Requires the ALTER ANY EVENT SESSION permission.

ExemplosExamples

O exemplo a seguir mostra como criar uma sessão de evento denominada test_session.The following example shows how to create an event session named test_session. Esse exemplo adiciona dois eventos e usa o destino Rastreamento de Eventos do Windows.This example adds two events and uses the Event Tracing for Windows target.

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émSee Also

ALTER EVENT SESSION (Transact-SQL) ALTER EVENT SESSION (Transact-SQL)
DROP EVENT SESSION (Transact-SQL) DROP EVENT SESSION (Transact-SQL)
server_event_sessions ( Transact-SQL ) sys.server_event_sessions (Transact-SQL)
xe_objects ( Transact-SQL ) sys.dm_xe_objects (Transact-SQL)
sys.dm_xe_object_columns (Transact-SQL)sys.dm_xe_object_columns (Transact-SQL)