Compartir a través de

ALTER EVENT SESSION (Transact-SQL)

Se aplica a:SQL ServerAzure 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 | DATABASE }
{
    [ [ {  <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 } ]
    [ [ , ] MAX_DURATION = { <time duration> { SECONDS | MINUTES | HOURS | DAYS } | UNLIMITED } ]
}

Argumentos

event_session_name

Nombre de una sesión de eventos existente.

STATE = START | PARAR

Inicia o detiene la sesión de eventos. El STATE argumento debe especificarse por sí mismo. No se puede combinar con ningún otro argumento de la misma ALTER EVENT SESSION instrucción.

AÑADIR EVENTO <event_specifier>

Identifica un evento que se va a asociar a la sesión de eventos. < > event_specifier está en forma de [event_module_guid].event_package_name. event_name, donde:

  • event_module_guid es el GUID del módulo que contiene el evento.
  • event_package_name es el paquete que contiene el evento.
  • event_name es el nombre del evento.

Para encontrar eventos disponibles, ejecute la consulta siguiente:

SELECT o.name AS event_name,
       o.description AS event_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'event'
ORDER BY event_name ASC;

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

Atributos personalizables para el evento.

Para encontrar atributos personalizables para un evento determinado, ejecute la consulta siguiente:

SELECT object_name,
       name AS column_name,
       type_name,
       column_value,
       description
FROM sys.dm_xe_object_columns
WHERE object_name = 'event-name-placeholder'
      AND column_type = 'customizable'
ORDER BY column_name ASC;

ACTION ( { [event_module_guid].event_package_name. action_name [ ,...n ] })

Acción que se va a asociar al evento, donde:

  • event_module_guid es el GUID del módulo que contiene la acción.
  • event_package_name es el paquete que contiene la acción.
  • action_name es el nombre de la acción.

Las acciones disponibles se pueden encontrar ejecutando la consulta siguiente:

SELECT o.name AS action_name,
       o.description AS action_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'action'
ORDER BY action_name ASC;

¿DÓNDE <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. Cada expresión de predicado está limitada a 3000 caracteres.

event_field_name

Nombre del campo de evento que identifica el origen del predicado.

Los campos de un evento se pueden encontrar ejecutando la consulta siguiente:

SELECT oc.name AS field_name,
       oc.type_name AS field_type,
       oc.description AS field_description
FROM sys.dm_xe_objects AS o
INNER JOIN sys.dm_xe_packages AS p
ON o.package_guid = p.guid
INNER JOIN sys.dm_xe_object_columns AS oc
ON o.name = oc.object_name
   AND
   o.package_guid = oc.object_package_guid
WHERE o.object_type = 'event'
      AND
      o.name = 'event-name-placeholder'
      AND
      oc.column_type = 'data'
ORDER BY field_name ASC;

[event_module_guid]. event_package_name. predicate_source_name

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 de origen del predicado.
  • predicate_source_name es el nombre del origen del predicado.

Los orígenes de predicado se pueden encontrar ejecutando la consulta siguiente:

SELECT o.name AS predicate_source_name,
       o.description AS predicate_source_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'pred_source'
ORDER BY predicate_source ASC;

[event_module_guid].event_package_name.predicate_compare_name

Nombre del objeto comparador de predicado, donde:

  • event_module_guid es el GUID del módulo que contiene el evento.
  • event_package_name es el paquete que contiene el objeto comparador de predicado.
  • predicate_compare_name es el nombre del comparador de predicados.

Los comparadores de predicados se pueden encontrar ejecutando la consulta siguiente:

SELECT o.name AS predicate_comparator_name,
       o.description AS predicate_comparator_description,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'pred_compare'
ORDER BY predicate_comparator ASC;

número

Cualquier tipo numérico que se pueda representar como un entero de 64 bits.

'string'

Una cadena ANSI o Unicode según sea necesario por el comparador 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 valor de un tipo inesperado, se produce un error.

EVENTO <DROP event_specifier>

Identifica un evento que se va a quitar de la sesión de eventos. El especificador de eventos está en forma de [event_module_guid]. event_package_name. event_name, 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.

    < > event_specifier debe identificar un evento que se agregó anteriormente a la sesión de eventos.

AGREGAR event_target_specifier DE DESTINO <>

Identifica un destino que se va a asociar a una sesión de eventos. El especificador de destino de eventos está en forma de [event_module_guid]. event_package_name. target_name, 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 nombre del destino.

Los destinos disponibles se pueden encontrar ejecutando la consulta siguiente:

SELECT o.name AS target_name,
       o.description AS target_description,
       o.capabilities_desc,
       p.name AS package_name,
       p.description AS package_description
FROM sys.dm_xe_objects AS o
     INNER JOIN sys.dm_xe_packages AS p
         ON o.package_guid = p.guid
WHERE o.object_type = 'target'
ORDER BY target_name ASC;

Una sesión de eventos puede tener cero, uno o varios destinos. Todos los destinos agregados a una sesión de eventos deben ser diferentes. Por ejemplo, no puede agregar un segundo event_file destino a una sesión que ya tenga un event_file destino.

Para obtener más información, incluidos ejemplos de uso para destinos usados habitualmente, consulte Destinos de eventos extendidos.

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 target-name-placeholder 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-placeholder';

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 de eventos extendidos.

LANZAR OBJETIVO <event_target_specifier>

Identifica un destino que se va a quitar de una sesión de eventos. El especificador de destino de eventos está en forma de [event_module_guid]. event_package_name. target_name, 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 nombre del destino.

El especificador de destino de eventos debe identificar un destino que se agregó anteriormente a la sesión de eventos.

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

Especifica las opciones que se van a usar con la sesión de eventos.

MAX_MEMORY = tamaño [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 (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 completos minimiza el impacto en el rendimiento, al tiempo que minimiza la pérdida 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 generalmente evita el impacto en el rendimiento en el servidor cuando los búferes de eventos se rellenan rápidamente, pero se pueden perder grandes cantidades 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. Es posible que las sesiones de usuario y las consultas se detengan mientras esperan a que los eventos se vacían del búfer.

    Nota:

    Para los destinos de archivo de eventos en Azure SQL Database e Instancia administrada de Azure SQL (con sql Server 2025 o Always-up-to-dateupdate policy), a partir de junio de 2024, NO_EVENT_LOSS se comporta igual que ALLOW_SINGLE_EVENT_LOSS. Si especifica NO_EVENT_LOSS, se devuelve una advertencia con el identificador de mensaje 25665, la gravedad 10 y el mensaje This target doesn't support the NO_EVENT_LOSS event retention mode. The ALLOW_SINGLE_EVENT_LOSS retention mode is used instead. 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 NO_EVENT_LOSS se usa con destinos de archivos de eventos en Azure Blob Storage.

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

MAX_DISPATCH_LATENCY = { segundos SEGUNDOS | 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.

  • sobras SOBRAS

    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.

  • INFINITO

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

MAX_EVENT_SIZE = tamaño [ 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 = { NINGUNA | PER_NODE | PER_CPU }

Especifica la afinidad de los búferes de eventos. Las opciones que no tienen como NONE resultado más búferes y un mayor consumo de memoria, pero pueden evitar contención y mejorar el rendimiento en máquinas más grandes.

  • NINGUNO

    Se crea un único conjunto de búferes en la instancia del motor de base de datos.

  • PER_NODE

    Se crea un conjunto de búferes para cada nodo NUMA.

  • PER_CPU

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

TRACK_CAUSALITY = { ON | OFF }

Especifica si se realiza un seguimiento de la causalidad de eventos o no. Si está habilitado, la causalidad permite correlacionar eventos relacionados en las diferentes conexiones con el servidor.

STARTUP_STATE = { ON | OFF }

Especifica si se inicia o no esta sesión de eventos automáticamente cuando se inicia el motor de base de datos.

Nota:

Si STARTUP_STATE = ONes , la sesión de eventos se inicia cuando se detiene el motor de base de datos y, a continuación, se reinicia. Para iniciar la sesión de eventos inmediatamente, use ALTER EVENT SESSION ... ON SERVER STATE = START.

  • ACTIVAR

    La sesión de eventos se inicia al iniciarse.

  • Apagado

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

MAX_DURATION = { duración del tiempo { SECONDS | MINUTOS | HORAS | DAYS } | UNLIMITED }

Aplica a: SQL Server 2025 (17.x)

  • ILIMITADO

    Hace que una sesión de eventos se ejecute indefinidamente una vez iniciada, hasta que se detenga mediante la ALTER EVENT SESSION ... STATE = STOP instrucción .

  • duración del tiempo SECONDS | MINUTOS | HORAS | DÍAS

    Hace que una sesión de eventos se detenga automáticamente después de que transcurre el tiempo especificado después de iniciar la sesión. La duración máxima admitida es de 2 147 483 segundos o 35 792 minutos o 596 horas o 24 días.

Para obtener más información, consulte Sesiones de eventos enlazadas a tiempo.

Comentarios

Para obtener más información sobre los argumentos de sesión de eventos, vea Sesiones de eventos extendidos.

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

Permisos

SQL Server e Instancia administrada de Azure SQL requieren el ALTER ANY EVENT SESSION permiso.

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

Sugerencia

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

Ejemplos

A. Iniciar y detener una sesión de eventos

Para usar este ejemplo con sesiones de eventos de base de datos, reemplace por ON SERVERON DATABASE.

ALTER EVENT SESSION test_session ON SERVER STATE = START;
ALTER EVENT SESSION test_session ON SERVER STATE = STOP;

B. Agregar nuevos eventos a una sesión existente

Para usar este ejemplo con sesiones de eventos de base de datos, reemplace por ON SERVERON DATABASE.

ALTER EVENT SESSION test_session ON SERVER
ADD EVENT sqlserver.database_transaction_begin,
ADD EVENT sqlserver.database_transaction_end;

C. Visualización de estadísticas de sesión

Para usar este ejemplo con sesiones de eventos de base de datos, reemplace por sys.dm_xe_sessionssys.dm_xe_database_sessionsy sys.dm_xe_session_events por sys.dm_xe_database_session_events.

SELECT *
FROM sys.dm_xe_sessions
WHERE name = 'test_session';

SELECT se.*
FROM sys.dm_xe_session_events AS se
WHERE EXISTS (SELECT 1
              FROM sys.dm_xe_sessions AS s
              WHERE s.address = se.event_session_address
                    AND s.name = 'test_session');

Contenido relacionado

  • Last updated on