ALTER EVENT SESSION (Transact-SQL)

Se aplica a: SQL Server Azure SQL Managed Instance

Inicia o detiene una sesión de eventos, o cambia la configuración de una sesión de eventos.

Convenciones de sintaxis de Transact-SQL

Sintaxis

ALTER EVENT SESSION event_session_name  
ON SERVER  
{  
    [ [ {  <add_drop_event> [ ,...n] }     
       | { <add_drop_event_target> [ ,...n ] } ]   
    [ WITH ( <event_session_options> [ ,...n ] ) ]  
    ]  
    | [ STATE = { START | STOP } ]  
}  
  
<add_drop_event>::=  
{  
    [ ADD EVENT <event_specifier>   
         [ ( {   
                 [ SET { event_customizable_attribute = <value> [ ,...n ] } ]  
                 [ ACTION ( { [event_module_guid].event_package_name.action_name [ ,...n ] } ) ]  
                 [ WHERE <predicate_expression> ]  
        } ) ]  
   ]   
   | DROP EVENT <event_specifier> }  
  
<event_specifier> ::=  
{  
[event_module_guid].event_package_name.event_name  
}  
  
<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'  
}  
  
<add_drop_event_target>::=  
{  
    ADD TARGET <event_target_specifier>  
        [ ( SET { target_parameter_name = <value> [ ,...n] } ) ]  
    | DROP TARGET <event_target_specifier>  
}  
  
<event_target_specifier>::=  
{  
    [event_module_guid].event_package_name.target_name  
}  
  
<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

Término	Definición
event_session_name	El nombre de una sesión de eventos existente.
STATE = START | STOP	Inicia o detiene la sesión de eventos. Este argumento solo es válido cuando ALTER EVENT SESSION se aplica a un objeto de sesión de eventos.
ADD EVENT <event_specifier>	Asocia el evento identificado por <event_specifier> con la sesión de eventos.
[event_module_guid] .event_package_name.event_name	El nombre de un evento en un paquete 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] }	Especifica 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 acción y el procesamiento de destino no se producen para este evento. Las expresiones de predicado se limitan 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. - 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. - predicate_compare_name es un origen global definido en la vista sys.dm_xe_objects como object_type "pred_compare".
DROP EVENT <event_specifier>	Quita el evento identificado por <event_specifier>. <event_specifier> debe ser válido en la sesión de eventos.
ADD TARGET <event_target_specifier>	Asocia el destino identificado por <event_target_specifier> con la sesión de eventos.
[event_module_guid].event_package_name.target_name	El nombre de un destino en 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 la acción. Las acciones 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. Nota: Si usa el destino de búfer de anillo, se recomienda establecer el parámetro de destino de max_memory en 2048 kilobytes (KB) para evitar posibles truncamientos de datos de la salida XML. Para más información sobre cuándo usar los diferentes tipos de destino, vea Destinos para eventos extendidos en SQL Server.
DROP TARGET <event_target_specifier>	Quita el destino identificado por <event_target_specifier>. <event_target_specifier> debe ser válido en la sesión de eventos.
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. 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. En el caso de los destinos de archivo de eventos en Azure SQL Database, se comporta igual que ALLOW_SINGLE_EVENT_LOSS. Para obtener más información, consulte EVENT_RETENTION_MODE.
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. El valor de latencia mínimo es de 1 segundo. Sin embargo, puede usarse el valor 0 para especificar la latencia INFINITE. De forma predeterminada, este valor está establecido en 30 segundos. 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. 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 MAX_EVENT_SIZE se establece, 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 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. Si STARTUP_STATE=ON, la sesión de eventos solo se inicia si SQL Server se detiene y, a continuación, se reinicia. ON = La sesión de eventos comienza en el inicio. OFF = La sesión de eventos NO comienza en el inicio.

Comentarios

Los ADD argumentos y DROP no se pueden usar en la misma instrucción.

Permisos

Requiere el permiso ALTER ANY EVENT SESSION.

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

En el ejemplo siguiente se inicia una sesión de eventos, se obtienen algunas estadísticas de la sesión activa y, a continuación, se agregan dos eventos a la sesión existente.

-- Start the event session  
ALTER EVENT SESSION test_session ON SERVER  
STATE = start;  
GO  

-- Obtain live session statistics   
SELECT * FROM sys.dm_xe_sessions;  
SELECT * FROM sys.dm_xe_session_events;  
GO  
  
-- Add new events to the session  
ALTER EVENT SESSION test_session ON SERVER  
ADD EVENT sqlserver.database_transaction_begin,  
ADD EVENT sqlserver.database_transaction_end;  
GO  

Consulte también

• CREATE EVENT SESSION (Transact-SQL)
• DROP EVENT SESSION (Transact-SQL)
• Destinos de SQL Server Extended Events
• sys.server_event_sessions (Transact-SQL)
• sys.dm_xe_objects (Transact-SQL)
• sys.dm_xe_object_columns (Transact-SQL)