CREATE EVENT SESSION (Transact-SQL)

Artículo
05/30/2024

Se aplica a: SQL Server Azure SQL Database Azure SQL Managed Instance

Crea una sesión de eventos extendidos 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 | DATABASE }
{  
    <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 "personalizable" 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, se quita el evento, lo que evita la acción adicional y el procesamiento de destino. Las expresiones de predicado están limitadas a 3000 caracteres.

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.
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 del predicado que se va a asociar con el 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.
predicate_compare_namees un origen global definido en la vista sys.dm_xe_objects como "pred_compare" object_type.

number es cualquier tipo numérico, incluido el tipo decimal. 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", ya sea 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 "destino" object_type.

SET { target_parameter_name= <value> [, ...n] }

Establece un parámetro de destino.

Para ver todos los parámetros de destino y sus descripciones, ejecute la consulta siguiente, reemplazando el target-name marcador de posición por el nombre de destino, como event_file, ring_buffer, histogram, etc.

SELECT name AS target_parameter_name,
       column_value AS default_value,
       description
FROM sys.dm_xe_object_columns
WHERE column_type = 'customizable'
      AND
      object_name = 'target-name';

Importante

Si usa el destino de búfer de anillo, se recomienda establecer el MAX_MEMORY parámetro de destino (distinto del MAX_MEMORY parámetro de sesión) en 1024 kilobytes (KB) o menos para ayudar a evitar el posible truncamiento de datos de la salida XML.

Para obtener más información sobre los tipos de destino, vea Destinos para eventos extendidos en SQL Server.

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 cantidad máxima no puede superar los 2 GB (menos de 2048 MB). Sin embargo, no se recomienda usar valores de memoria en el intervalo de GB.

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, del particionamiento de la memoria y del 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 retienen todos los eventos que aparecen. 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. El uso de NO_EVENT_LOSS puede provocar problemas de rendimiento detectables 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.

Nota:

Para los destinos de archivo de eventos en Azure SQL Database y en Azure SQL Instancia administrada con la directiva de actualización siempre actualizada, a partir de junio de 2024, NO_EVENT_LOSS se comporta igual que ALLOW_SINGLE_EVENT_LOSS. Si especifica NO_EVENT_LOSS, una advertencia con el identificador de mensaje 25665, la gravedad 10 y el mensaje Este destino no admite el modo de retención de eventos NO_EVENT_LOSS. En su lugar, se usa el modo de retención de ALLOW_SINGLE_EVENT_LOSS. se devuelve y se crea la sesión.

Este cambio evita tiempos de espera de conexión, retrasos de conmutación por error y otros problemas que pueden reducir la disponibilidad de la base de datos cuando se usa NO_EVENT_LOSS con destinos de archivos de eventos en Azure Blob Storage.

NO_EVENT_LOSS se quitarán como argumento de EVENT_RETENTION_MODE admitido en futuras actualizaciones de Azure SQL Database y Azure SQL Instancia administrada. Evite utilizar esta característica en nuevos trabajos de desarrollo y tenga previsto modificar las aplicaciones que actualmente la utilizan.

MAX_DISPATCH_LATENCY = { seconds SECONDS | INFINITE }

Especifica el tiempo que los eventos se almacenan en memoria antes de enviarse a los destinos de la sesión de eventos. De forma predeterminada, este valor está establecido en 30 segundos.

seconds SECONDS. El tiempo, en segundos, que hay que esperar antes de que empiecen a variarse 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 debe establecerse para permitir eventos únicos mayores que MAX_MEMORY; si se establece en menos de MAX_MEMORY se produce un error. size es un número entero y puede expresarse en kilobytes (KB) o en megabytes (MB). Si size se especifica en kilobytes, el tamaño mínimo permitido es 64 KB. Cuando se establece MAX_EVENT_SIZE, se crean dos búferes de tamaño además de MAX_MEMORY y la memoria total usada para el almacenamiento en búfer de eventos se 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 conjunto de búferes por cada nodo NUMA.

PER_CPU: se crea un conjunto de búferes por 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 SQL Server se detiene y después se reinicia.

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

En SQL Server y SQL Instancia administrada, requiere el CREATE ANY EVENT SESSION permiso (introducido en SQL Server 2022).ALTER ANY EVENT SESSION

En SQL Database, se requiere el permiso ALTER ANY DATABASE EVENT SESSION en la base de datos.

Sugerencia

SQL Server 2022 introdujo una serie de nuevos permisos más pormenorizados para eventos extendidos. Para obtener más información, vea Blog: Nuevos permisos granulares para SQL Server 2022 y Azure SQL para mejorar el cumplimiento con PoLP.

Ejemplos

Ejemplo de SQL Server

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

Ejemplo de Azure SQL

En Azure SQL Managed Instance o Azure SQL Database, almacene archivos .xel en Azure Blob Storage. Puede usar sys.fn_xe_file_target_read_file para leer las sesiones de eventos extendidas que cree y almacene en Azure Blob Storage. Por ejemplo, consulte Código de destino del archivo de evento para eventos extendidos en Azure SQL Database y SQL Managed Instance.

Los ejemplos de código pueden diferir para Azure SQL Database y SQL Managed Instance

Algunos ejemplos de código de Transact-SQL escritos para SQL Server necesitan pequeños cambios para ejecutarse en Azure. Una categoría de estos ejemplos de código implica vistas de catálogo cuyos prefijos de nombre difieren en función del tipo de motor de base de datos:

server_ - prefijo para SQL Server y Azure SQL Managed Instance
database_ - prefijo para Azure SQL Database y SQL Managed Instance

Azure SQL Database admite solo sesiones de eventos con ámbito de base de datos. SQL Server Management Studio (SSMS) es totalmente compatible con sesiones de eventos con ámbito de base de datos de Azure SQL Database: en cada base de datos del Explorador de objetos aparece un nodo Eventos extendidos que contiene sesiones con ámbito de base de datos.

Azure SQL Managed Instance admite sesiones tanto con ámbito de base de datos como con ámbito de servidor. SSMS admite completamente sesiones con ámbito de servidor para SQL Managed Instance: en la carpeta Administración de cada instancia administrada del Explorador de objetos aparece un nodo Eventos extendidos que contiene todas las sesiones con ámbito de servidor.

Nota:

En las instancias administradas, se recomienda usar sesiones con ámbito de servidor. Las sesiones con ámbito de base de datos no se muestran en el Explorador de objetos en SSMS para Azure SQL Managed Instance. Este tipo de sesiones solo se pueden consultar y administrar con Transact-SQL cuando se usa una instancia administrada.

Como ilustración, en la tabla siguiente se enumeran y comparan dos subconjuntos de las vistas de catálogo. Por motivos de brevedad, los subconjuntos están restringidos a los nombres de vista que también contienen la cadena _event. Los subconjuntos tienen prefijos de nombre diferentes porque admiten diferentes motores de base de datos.

Nombre en SQL Server y Azure SQL Managed Instance	Nombre en Azure SQL Database y Azure SQL Managed Instance
server_event_notifications server_event_session_actions server_event_session_events server_event_session_fields server_event_session_targets server_event_sessions server_events server_trigger_events	database_event_session_actions database_event_session_events database_event_session_fields database_event_session_targets database_event_sessions

Las dos listas de la tabla anterior eran precisas a partir de marzo de 2022. Para obtener una lista actualizada, ejecute la siguiente instrucción SELECT de Transact-SQL:

SELECT name
    FROM sys.all_objects
    WHERE
        (name LIKE 'database[_]%' OR
         name LIKE 'server[_]%' )
        AND name LIKE '%[_]event%'
        AND type = 'V'
        AND SCHEMA_NAME(schema_id) = 'sys'
    ORDER BY name;

Compartir vía

CREATE EVENT SESSION (Transact-SQL)

Sintaxis

Argumentos

event_session_name

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>

ADD TARGET [event_module_guid].event_package_name.target_name

SET { target_parameter_name= <value> [, ...n] }

WITH ( <event_session_options> [ ,...n] )

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 }

Comentarios

Permisos

Ejemplos

Ejemplo de SQL Server

Ejemplo de Azure SQL

Los ejemplos de código pueden diferir para Azure SQL Database y SQL Managed Instance

Consulte también

Pasos siguientes

Comentarios

Recursos adicionales