CREATE EVENT SESSION (Transact-SQL)

Crea un objeto de sesión de Extended Events que identifica el origen de los eventos, los destinos de la sesión de eventos y las opciones de la sesión de eventos.

Convenciones de sintaxis de Transact-SQL.

Sintaxis

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
  Es el nombre definido por el usuario para identificar la sesión de eventos. event_session_name es alfanumérico, puede tener hasta 128 caracteres, debe ser único dentro de una instancia de SQL Server y debe cumplir las reglas de los identificadores.

• ADD EVENT [ event_module_guid ].event_package_name.event_name
  Es el evento que se va a asociar con la sesión de eventos, donde:

  • event_module_guid es el GUID del módulo que contiene el evento.

  • event_package_name es el paquete que contiene el objeto de la acción.

  • event_name es el objeto de evento.

  Los eventos aparecen en la vista sys.dm_xe_objects como object_type 'event'.

• SET { event_customizable_attribute= <value> [ ,...n] }
  Permite establecer los atributos personalizables del evento. Los atributos personalizables aparecen en la vista sys.dm_xe_object_columns como column_type 'customizable ' y object_name = event_name.

• ACTION ( { [event_module_guid].event_package_name.action_name [ ,...n] })
  Es la acción que se va a asociar a la sesión de eventos, donde:

  • event_module_guid es el GUID del módulo que contiene el evento.

  • event_package_name es el paquete que contiene el objeto de la acción.

  • action_name es el objeto de la acción.

  Las acciones aparecen en la vista sys.dm_xe_objects como object_type 'action'.

• WHERE <predicate_expression>
  Especifica la expresión de predicado usada para determinar si debe procesarse un evento. Si <predicate_expression> es true, las acciones y los destinos de la sesión siguen procesando el evento. Si <predicate_expression> es false, la sesión elimina el evento antes de que las acciones y los destinos de la sesión lo procesen. Las expresiones de predicado están limitadas a 3000 caracteres, lo que limita los argumentos de cadena.

• event_field_name
  Es el nombre del campo de evento que identifica el origen del predicado.

• [event_module_guid].event_package_name.predicate_source_name
  Es el nombre del origen del predicado global, donde:

  • event_module_guid es el GUID del módulo que contiene el evento.

  • event_package_name es el paquete que contiene el objeto del predicado.

  • El parámetro predicate_source_name se define en la vista sys.dm_xe_objects como object_type 'pred_source'.

• [event_module_guid].event_package_name.predicate_compare_name
  Es el nombre del objeto de predicado que se va a asociar al evento, donde:

  • event_module_guid es el GUID del módulo que contiene el evento.

  • event_package_name es el paquete que contiene el objeto del predicado.

  • El parámetro predicate_compare_name es un origen global definido en la vista sys.dm_xe_objects como object_type 'pred_compare'.

• number
  Es cualquier tipo numérico, decimal incluido. Las limitaciones son la falta de memoria física disponible o un número demasiado grande para ser representado como un entero de 64 bits.

• 'string'
  Una cadena ANSI o Unicode según lo requerido por la comparación de predicado. No se realiza ninguna conversión implícita de tipos de cadena para las funciones de comparación de predicado. Si se pasa el tipo incorrecto se producirá un error.

• ADD TARGET [event_module_guid].event_package_name.target_name
  Es el destino que se va a asociar con la sesión de eventos, donde:

  • event_module_guid es el GUID del módulo que contiene el evento.

  • event_package_name es el paquete que contiene el objeto de la acción.

  • target_name es el destino. Los destinos aparecen en la vista sys.dm_xe_objects como object_type 'target'.

• SET { target_parameter_name= <value> [, ...n] }
  Establece un parámetro de destino. Los parámetros de destino aparecen en la vista sys.dm_xe_object_columns como column_type 'customizable' y object_name = target_name.

  Importante
  Si usa el destino de búfer en anillo, se recomienda que establezca el parámetro de destino max_memory en 2048 kilobytes (KB) para intentar evitar el truncamiento de los datos en la salida XML. Para obtener más información acerca de cuándo se usan los distintos tipos de destino, vea Destinos de SQL Server Extended Events.

• WITH ( <event_session_options> [ ,...n] )
  Especifica las opciones que se utilizarán con la sesión de eventos.

• MAX_MEMORY =size [ KB | MB ]
  Especifica la cantidad máxima de memoria que se asigna a la sesión para el almacenamiento en búfer de los eventos. El valor predeterminado es 4 MB. size es un número entero y puede expresarse en kilobytes (KB) o en megabytes (MB). La memoria asignada para los destinos asincrónicos es independiente de este valor.

• EVENT_RETENTION_MODE = { ALLOW_SINGLE_EVENT_LOSS | ALLOW_MULTIPLE_EVENT_LOSS | NO_EVENT_LOSS }
  Especifica el modo de retención de eventos usado para controlar las pérdidas de eventos.

  • ALLOW_SINGLE_EVENT_LOSS
    Puede perderse un evento de la sesión. Se elimina un único evento solo cuando todos los búferes de eventos están llenos. La pérdida de un único evento cuando los búferes de eventos están llenos permite un rendimiento de SQL Server aceptable, al mismo tiempo que minimiza las pérdidas de datos en el flujo de eventos procesado.

  • ALLOW_MULTIPLE_EVENT_LOSS
    En la sesión pueden perderse búferes completos de eventos que contienen varios eventos. El número de eventos perdidos depende del tamaño de la memoria asignada a la sesión, el particionamiento de la memoria y el tamaño de los eventos del búfer. Esta opción minimiza el impacto en el rendimiento del servidor si los búferes de eventos se llenan rápidamente, pero se puede perder un gran número de eventos de la sesión.

  • NO_EVENT_LOSS
    No se permite ninguna pérdida de eventos. Esta opción asegura que se van a retener todos los eventos que aparezcan. Al utilizar esta opción, se obliga a todas las tareas que activan eventos a esperar hasta que haya espacio disponible en un búfer de eventos. Esto puede producir problemas detectables de rendimiento mientras la sesión de eventos está activa. Las conexiones de usuario pueden detenerse a la espera de que se quiten eventos del búfer.

• MAX_DISPATCH_LATENCY = { seconds SECONDS | INFINITE }
  Especifica el tiempo que los eventos se almacenarán en memoria antes de enviarse a los destinos de la sesión de eventos. Este valor se establece en 30 segundos de forma predeterminada.

  • seconds SECONDS
    Tiempo, en segundos, que hay que esperar antes de que empiecen a vaciarse los búferes en los destinos. seconds es un número entero. El valor de latencia mínimo es de 1 segundo. Sin embargo, puede usarse el valor 0 para especificar la latencia INFINITE.

  • INFINITE
    Los búferes se vacían en los destinos solo si están llenos o cuando se cierra la sesión de eventos.

    Nota

    MAX_DISPATCH_LATENCY = 0 SECONDS es equivalente a MAX_DISPATCH_LATENCY = INFINITE.

• MAX_EVENT_SIZE =size [ KB | MB ]
  Especifica el tamaño máximo permitido para los eventos. MAX_EVENT_SIZE solo se debería establecer para permitir los eventos únicos mayores que MAX_MEMORY; al establecerlo en un valor menor que MAX_MEMORY, se producirá un error. size es un número entero y puede indicar kilobytes (KB) o megabytes (MB). Si size se especifica en kilobytes, el mínimo tamaño permitido es 64 KB. Cuando se establece MAX_EVENT_SIZE, se crean dos búferes de size además de MAX_MEMORY. Esto significa que la memoria total utilizada en búferes de eventos es MAX_MEMORY + 2 * MAX_EVENT_SIZE.

• MEMORY_PARTITION_MODE = { NONE | PER_NODE | PER_CPU }
  Especifica la ubicación en la que se van a crear los búferes de eventos.

  • NONE
    Se crea un conjunto único de búferes dentro de la instancia de SQL Server.

  • PER_NODE
    Se crea un único conjunto de búferes por cada nodo NUMA. Para obtener más información, vea Descripción del acceso no uniforme a memoria.

  • PER_CPU
    Se crea un conjunto de búferes para cada CPU.

• TRACK_CAUSALITY = { ON | OFF }
  Especifica si se va a realizar el seguimiento de la causalidad. Si está habilitado, la causalidad permite correlacionar eventos relacionados en las diferentes conexiones con el servidor.

• STARTUP_STATE = { ON | OFF }
  Especifica si esta sesión de eventos se inicia automáticamente cuando se inicie SQL Server.

  Nota

  Si STARTUP_STATE = ON, la sesión de eventos se iniciará solo si se detiene SQL Server y se reinicia a continuación.

  • ON
    La sesión de eventos se inicia en el inicio.

  • OFF
    La sesión de eventos no se inicia en el inicio.

Comentarios

El orden de prioridad de los operadores lógicos es NOT (el más alto), seguido de AND y OR.

Permisos

Requiere el permiso CONTROL SERVER.

Ejemplos

En el ejemplo siguiente se muestra cómo crear una sesión de eventos denominada test_session. En este ejemplo se agregan dos eventos y utiliza el Seguimiento de eventos para 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

Vea también

Referencia

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)