estructura EVENT_TRACE_PROPERTIES (evntrace.h)

La estructura EVENT_TRACE_PROPERTIES contiene información sobre una sesión de seguimiento de eventos. Esta estructura se usa con API como StartTrace y ControlTrace al definir, actualizar o consultar las propiedades de una sesión.

Nota:

Se trata de una estructura de la versión 1. Las opciones adicionales son compatibles con EVENT_TRACE_PROPERTIES_V2 (por ejemplo , FilterDesc y V2Options).

Sintaxis

typedef struct _EVENT_TRACE_PROPERTIES {
  WNODE_HEADER Wnode;
  ULONG        BufferSize;
  ULONG        MinimumBuffers;
  ULONG        MaximumBuffers;
  ULONG        MaximumFileSize;
  ULONG        LogFileMode;
  ULONG        FlushTimer;
  ULONG        EnableFlags;
  union {
    LONG AgeLimit;
    LONG FlushThreshold;
  } DUMMYUNIONNAME;
  ULONG        NumberOfBuffers;
  ULONG        FreeBuffers;
  ULONG        EventsLost;
  ULONG        BuffersWritten;
  ULONG        LogBuffersLost;
  ULONG        RealTimeBuffersLost;
  HANDLE       LoggerThreadId;
  ULONG        LogFileNameOffset;
  ULONG        LoggerNameOffset;
} EVENT_TRACE_PROPERTIES, *PEVENT_TRACE_PROPERTIES;

Miembros

Wnode

Estructura WNODE_HEADER . Debe especificar los miembros BufferSize, Flags y Guid . Opcionalmente, puede especificar el miembro ClientContext .

BufferSize

Kilobytes de memoria asignada para cada búfer de sesión de seguimiento de eventos. El tamaño mínimo del búfer es de 4 (4 KB). El tamaño máximo del búfer es 16384 (16 MB). La mayoría de las sesiones de seguimiento deben usar un tamaño de búfer de 64 KB o menos para evitar perder memoria y espacio en disco. Antes de Windows 8: el tamaño máximo del búfer es 1024 (1 MB).

Los tamaños de búfer más pequeños reducen el uso de memoria de sesión y pueden ayudar a reducir el tamaño del archivo de registro. Los tamaños de búfer más grandes admiten la recopilación de eventos más grandes porque ETW no fragmenta eventos a través de los límites del búfer y, por lo tanto, no pueden recopilar eventos mayores que el tamaño del búfer. En escenarios que implican un rendimiento de datos extremadamente alto, los tamaños de búfer más grandes también pueden reducir la sobrecarga de CPU.

• Una sesión con eventos pequeños y una tasa de eventos baja (unos pocos KB/s) debe usar un tamaño de búfer pequeño (de 4 KB a 16 KB).
• Una sesión con eventos pequeños y una tasa de eventos moderada debe usar un tamaño de búfer mediano (de 16 KB a 32 KB).
• Una sesión con eventos grandes o una tasa de eventos alta (unos pocos MB/s) debe usar un tamaño de búfer grande (de 64 KB a 128 KB).
• En raras ocasiones, cuando se debe reservar una gran cantidad de memoria para un seguimiento de diagnóstico con cientos de megabytes de datos por segundo, un tamaño de búfer enorme (256 KB a 1024 KB) puede reducir la sobrecarga de CPU.

Nota:

Independientemente del tamaño del búfer, ETW no puede recopilar eventos de más de 64 KB.

ETW puede ajustar el bufferSize solicitado hacia arriba en determinados escenarios. Por ejemplo, al escribir un archivo de seguimiento en un disco, ETW puede aumentar el tamaño del búfer a un múltiplo del tamaño de bloque físico del disco.

Importante

BufferSize es uno de los parámetros más importantes para una sesión de seguimiento. Los búferes grandes suelen desperdiciar memoria y espacio en disco. Las sesiones de seguimiento con búferes grandes (256 KB o más) solo se deben usar para investigaciones de diagnóstico o pruebas, no para el seguimiento de producción.

Sugerencia

No use BufferSize para controlar el uso de memoria de la sesión de seguimiento. En su lugar, seleccione el tamaño del búfer en función del tamaño de evento y la tasa de eventos de la sesión y, a continuación, use los parámetros MinimumBuffers y MaximumBuffers para ajustar el uso de memoria de la sesión.

MinimumBuffers

Número mínimo de búferes reservados para el grupo de búferes de la sesión de seguimiento.

ETW puede ajustar este valor en determinados escenarios.

• Si el modo de registro incluye la EVENT_TRACE_NO_PER_PROCESSOR_BUFFERING marca, ETW reservará al menos 2 búferes.
• Si el modo de registro no incluye la EVENT_TRACE_NO_PER_PROCESSOR_BUFFERING marca , ETW reservará al menos 2 búferes para cada procesador lógico.
• Si este valor es mayor que un límite determinado por ETW, ETW puede reducirlo al límite para evitar un uso excesivo de memoria.

Para el modo de archivo y los seguimientos en tiempo real con velocidades de eventos moderadas, la mayoría de los usuarios deben minimizar el uso de memoria estableciendo MinimumBuffers en 0 o en un mínimo pequeño (por ejemplo, 4 o 8), lo que permite a ETW ajustar el valor hacia arriba en función del número de procesadores. ETW reservará el número mínimo (ajustado) de búferes cuando se inicie el seguimiento. Si los búferes se rellenan más rápidamente de lo que se pueden procesar, ETW intentará asignar búferes de adición, hasta el número especificado por MaximumBuffers.

En el caso de los seguimientos en modo de almacenamiento en búfer (circular en memoria), los usuarios deben establecer el parámetro MinimumBuffers según la cantidad total de memoria que desea que ETW reserve para la sesión. Normalmente, esto se calcula en función de la tasa de eventos esperada y la cantidad de tiempo que desea que se cubra el seguimiento. Por ejemplo, si espera una velocidad de datos de 16 KB por segundo y desea que el seguimiento registre al menos 60 segundos de datos, necesitará 960 KB. Suponiendo que un tamaño de búfer de 32 KB, establecería MinimumBuffers en 30 (total de 960 KB / 32 KB por búfer = 30 búferes). ETW reservará el número mínimo (ajustado) de búferes cuando se inicie el seguimiento. Cuando se rellenan todos los búferes, ETW reutilizará el búfer rellenado más antiguo para los nuevos eventos. Tenga en cuenta que ETW no asignará búferes adicionales (ETW omite MaximumBuffers para seguimientos en modo de almacenamiento en búfer).

MaximumBuffers

Número máximo de búferes que se asignarán para el grupo de búferes de la sesión de seguimiento.

ETW puede ajustar este valor en determinados escenarios.

• Si este valor es menor que el valor ajustado de MinimumBuffers, ETW puede aumentarlo a un valor adecuado igual o mayor que MinimumBuffers.
• Si este valor es mayor que un límite determinado por ETW, ETW puede reducirlo al límite.

La mayoría de los usuarios deben empezar a ajustar su sesión estableciendo MinimumBuffers y MaximumBuffers en el mismo valor. A continuación, puede aumentar el valor de MaximumBuffers si el seguimiento quita eventos durante los picos de velocidad de eventos.

ETW no puede asignar búferes a petición si un controlador que se ejecuta en IRQL elevado genera el evento. Si la sesión de seguimiento necesita registrar eventos de proveedores de modo kernel de IRQL altos, es posible que tenga que usar un valor mayor de MinimumBuffers para forzar la asignación previa de los búferes.

Nota

ETW omite MaximumBuffers para las sesiones en modo de almacenamiento en búfer (sesiones que incluyen el modo EVENT_TRACE_BUFFERING_MODEde registro ). Las sesiones en modo de almacenamiento en búfer siempre asignan MinimumBuffers al principio de la colección de seguimiento y nunca asignan búferes adicionales.

MaximumFileSize

Tamaño máximo del archivo usado para registrar eventos, en megabytes o cero sin límite de tamaño. Normalmente, se usa este miembro para limitar el tamaño de un archivo de registro circular al establecer LogFileMode en EVENT_TRACE_FILE_MODE_CIRCULAR. Este miembro debe establecerse en un valor distinto de cero si LogFileMode contiene EVENT_TRACE_FILE_MODE_PREALLOCATE, EVENT_TRACE_FILE_MODE_CIRCULAR o EVENT_TRACE_FILE_MODE_NEWFILE.

Si usa la unidad del sistema (la unidad que contiene el sistema operativo) para el registro, ETW comprueba si hay más de 200 MB de espacio en disco, independientemente de si usa el parámetro de tamaño máximo de archivo. Por lo tanto, si especifica 100 MB como tamaño máximo de archivo para el archivo de seguimiento en la unidad del sistema, debe tener 300 MB de espacio libre en la unidad.

LogFileMode

Marcas de registro para la sesión de seguimiento de eventos. Este miembro se usa para especificar si desea que los eventos se escriban en un búfer circular en memoria, un archivo de registro o un consumidor en tiempo real. También puede usar este miembro para especificar otras características de sesión, por ejemplo, que la sesión es una sesión de registrador privado. Para obtener una lista de las posibles marcas, consulte Constantes del modo de registro.

ETW almacena en búfer eventos para sesiones en tiempo real cuando no hay ningún consumidor en tiempo real para la sesión. Tenga en cuenta que este almacenamiento en búfer está limitado. Si se alcanza el límite, se omitirán los nuevos eventos y se producirá un error en las funciones de registro con STATUS_LOG_FILE_FULL. Antes de Windows Vista: Si no hay ningún consumidor en tiempo real, los eventos se descartan y el registro continúa.

No inicie una sesión de registro en tiempo real a menos que un consumidor en tiempo real consuma los eventos. Una sesión en tiempo real sin consumidores desperdiciará recursos del sistema (CPU, memoria y espacio en disco para almacenar en búfer los eventos).

Si un consumidor comienza a procesar eventos en tiempo real, los eventos almacenados en búfer se consumen primero. Una vez consumidos todos los eventos almacenados en búfer, la sesión comenzará a notificar nuevos eventos.

FlushTimer

Con qué frecuencia, en segundos, se vacían los búferes de seguimiento no vacíos. El tiempo de vaciado mínimo es de 1 segundo.

• Para las sesiones en modo de archivo: si se establece FlushTimer en 0, se deshabilitarán los vaciados basados en tiempo (el vaciado se producirá cuando se rellene el búfer, cuando se detenga la sesión o cuando la sesión se vacía explícitamente). La mayoría de los seguimientos del modo de archivo deben establecer FlushTimer en 0 para evitar el espacio desperdiciado en el archivo de seguimiento (es decir, para que el espacio en disco no se haya desperdiciado almacenando búferes principalmente vacíos). Es posible que desee establecer el temporizador en un valor distinto de cero si existe la posibilidad de que el seguimiento no se cierre (por ejemplo, si desea asegurarse de obtener eventos incluso si el sistema se bloquea).
• Para las sesiones en tiempo real: si se establece FlushTimer en 0, se habilitará un tiempo de espera predeterminado de 1 segundo. Las sesiones en tiempo real deben establecer el temporizador de vaciado en función de la rapidez con la que se deben recibir los datos. Tenga en cuenta que un valor de temporizador mayor reducirá la sobrecarga de CPU para el seguimiento. La mayoría de los seguimientos en tiempo real deben comenzar con un temporizador de 5 o 10 segundos y ajustar el temporizador en función de la necesidad.
• En el caso de las sesiones almacenadas en búfer (circular en memoria), no se usa FlushTimer . Los datos de seguimiento solo se vaciarán a petición (es decir, se vaciarán en un archivo a través de ControlTrace).

EnableFlags

Una sesión del registrador del sistema puede establecer EnableFlags para indicar qué eventos systemTraceProvider deben incluirse en el seguimiento.

Nota:

EnableFlags solo es válido para los registradores del sistema, es decir, las sesiones de seguimiento que se inician con la EVENT_TRACE_SYSTEM_LOGGER_MODE marca de modo registrador, el KERNEL_LOGGER_NAME nombre de la sesión, el SystemTraceControlGuid GUID de sesión o el GUID de GlobalLoggerGuid sesión.

Este miembro puede contener uno o varios de los valores siguientes. Además de los eventos que especifique, a menos que especifique EVENT_TRACE_FLAG_NO_SYSCONFIG, el registrador también registra eventos de configuración de hardware en Windows XP y eventos de configuración del sistema en Windows Server 2003 o posterior.

• EVENT_TRACE_FLAG_ALPC (0x00100000)

  Habilita los tipos de eventos ALPC .

  Este valor se admite en Windows Vista y versiones posteriores.

• EVENT_TRACE_FLAG_CSWITCH (0x00000010)

  Habilita el siguiente tipo de evento Thread :

  • CSwitch

  Este valor se admite en Windows Vista y versiones posteriores.

• EVENT_TRACE_FLAG_DBGPRINT (0x00040000)

  Permite convertir las llamadas DbgPrint y DbgPrintEx a eventos ETW.

• EVENT_TRACE_FLAG_DISK_FILE_IO (0x00000200)

  Habilita el siguiente tipo de evento FileIo (también debe habilitar EVENT_TRACE_FLAG_DISK_IO):

  • FileIo_Name

• EVENT_TRACE_FLAG_DISK_IO (0x00000100)

  Habilita los siguientes tipos de eventos DiskIo :

  • DiskIo_TypeGroup1
  • DiskIo_TypeGroup3

• EVENT_TRACE_FLAG_DISK_IO_INIT (0x00000400)

  Habilita el siguiente tipo de evento DiskIo :

  • DiskIo_TypeGroup2

  Este valor se admite en Windows Vista y versiones posteriores.

• EVENT_TRACE_FLAG_DISPATCHER (0x00000800)

  Habilita el siguiente tipo de evento Thread :

  • ReadyThread

  Este valor se admite en Windows 7, Windows Server 2008 R2 y versiones posteriores.

• EVENT_TRACE_FLAG_DPC (0x00000020)

  Habilita el siguiente tipo de evento PerfInfo :

  • DPC

  Este valor se admite en Windows Vista y versiones posteriores.

• EVENT_TRACE_FLAG_DRIVER (0x00800000)

  Habilita los siguientes tipos de eventos DiskIo :

  • DriverCompleteRequest
  • DriverCompleteRequestReturn
  • DriverCompletionRoutine
  • DriverMajorFunctionCall
  • DriverMajorFunctionReturn

  Este valor se admite en Windows Vista y versiones posteriores.

• EVENT_TRACE_FLAG_FILE_IO (0x02000000)

  Habilita los siguientes tipos de eventos FileIo :

  • FileIo_OpEnd

  Este valor se admite en Windows Vista y versiones posteriores.

• EVENT_TRACE_FLAG_FILE_IO_INIT (0x04000000)

  Habilita el siguiente tipo de evento FileIo :

  • FileIo_Create
  • FileIo_DirEnum
  • FileIo_Info
  • FileIo_ReadWrite
  • FileIo_SimpleOp

  Este valor se admite en Windows Vista y versiones posteriores.

• EVENT_TRACE_FLAG_IMAGE_LOAD (0x00000004)

  Habilita el siguiente tipo de evento Image :

  • Image_Load

• EVENT_TRACE_FLAG_INTERRUPT (0x00000040)

  Habilita el siguiente tipo de evento PerfInfo :

  • ISR

  Este valor se admite en Windows Vista y versiones posteriores.

• EVENT_TRACE_FLAG_JOB (0x00080000)

  Este valor se admite en Windows 10

• EVENT_TRACE_FLAG_MEMORY_HARD_FAULTS (0x00002000)

  Habilita el siguiente tipo de evento PageFault_V2 :

  • PageFault_HardFault

• EVENT_TRACE_FLAG_MEMORY_PAGE_FAULTS (0x00001000)

  Habilita el siguiente tipo de evento PageFault_V2 :

  • PageFault_TypeGroup1

• EVENT_TRACE_FLAG_NETWORK_TCPIP (0x00010000)

  Habilita los tipos de eventos TcpIp y UdpIp .

• EVENT_TRACE_FLAG_NO_SYSCONFIG (0x10000000)

  No realice una ejecución de configuración del sistema.

  Este valor se admite en Windows 8, Windows Server 2012 y versiones posteriores.

• EVENT_TRACE_FLAG_PROCESS (0x00000001)

  Habilita el siguiente tipo de evento Process :

  • Process_TypeGroup1

• EVENT_TRACE_FLAG_PROCESS_COUNTERS (0x00000008)

  Habilita el siguiente tipo de evento Process_V2 :

  • Process_V2_TypeGroup2

  Este valor se admite en Windows Vista y versiones posteriores.

• EVENT_TRACE_FLAG_PROFILE (0x01000000)

  Habilita el siguiente tipo de evento PerfInfo :

  • SampledProfile

  Este valor se admite en Windows Vista y versiones posteriores.

• EVENT_TRACE_FLAG_REGISTRY (0x00020000)

  Habilita los tipos de eventos del Registro .

• EVENT_TRACE_FLAG_SPLIT_IO (0x00200000)

  Habilita los tipos de eventos SplitIo .

  Este valor se admite en Windows Vista y versiones posteriores.

• EVENT_TRACE_FLAG_SYSTEMCALL (0x00000080)

  Habilita el siguiente tipo de evento PerfInfo :

  • SysCallEnter
  • SysCallExit

  Este valor se admite en Windows Vista y versiones posteriores.

• EVENT_TRACE_FLAG_THREAD (0x00000002)

  Habilita el siguiente tipo de evento Thread :

  • Thread_TypeGroup1

• EVENT_TRACE_FLAG_VAMAP (0x00008000)

  Habilita el tipo de evento map y unmap (excluyendo los archivos de imagen).

  Este valor se admite en Windows 8, Windows Server 2012 y versiones posteriores.

• EVENT_TRACE_FLAG_VIRTUAL_ALLOC (0x00004000)

  Habilita el siguiente tipo de evento PageFault_V2 :

  • PageFault_VirtualAlloc

  Este valor se admite en Windows 7, Windows Server 2008 R2 y versiones posteriores.

DUMMYUNIONNAME

DUMMYUNIONNAME.AgeLimit

No se usa.

Windows 2000: Retraso de tiempo antes de liberar los búferes sin usar, en minutos. El valor predeterminado es 15 minutos.

DUMMYUNIONNAME.FlushThreshold

NumberOfBuffers

En la salida, el número de búferes asignados para el grupo de búferes de la sesión de seguimiento de eventos.

FreeBuffers

En la salida, el número de búferes que se asignan pero que no se usan en el grupo de búferes de la sesión de seguimiento de eventos.

EventsLost

En la salida, el número de eventos que no se registraron.

BuffersWritten

En la salida, el número de búferes escritos.

LogBuffersLost

En la salida, el número de búferes que no se pudieron escribir en el archivo de registro.

RealTimeBuffersLost

En la salida, el número de búferes que no se pudieron entregar en tiempo real al consumidor.

LoggerThreadId

En la salida, el identificador del subproceso de la sesión de seguimiento de eventos.

LogFileNameOffset

Desplazamiento (en bytes) desde el principio de la memoria asignada de esta estructura hasta el principio de la cadena terminada en nul que contiene el nombre del archivo de registro.

El nombre de archivo normalmente tiene una .etl extensión. Todas las carpetas de la ruta de acceso ya deben existir (ETW no creará carpetas automáticamente). La ruta de acceso puede ser relativa, absoluta, local o remota. Las variables de entorno de la ruta de acceso no se expandirán. El usuario debe tener permiso para escribir en la carpeta.

El nombre del archivo de registro está limitado a 1024 caracteres. Si establece LogFileMode en EVENT_TRACE_PRIVATE_LOGGER_MODE o EVENT_TRACE_FILE_MODE_NEWFILE, asegúrese de reservar suficiente memoria para incluir el identificador de proceso que se anexará al nombre de archivo para las sesiones de registradores privados y el número secuencial que se agrega a los archivos de registro creados con el nuevo modo de registro de archivos.

Si no desea registrar eventos en un archivo de registro (por ejemplo, si especifica solo EVENT_TRACE_REAL_TIME_MODE ), establezca LogFileNameOffset en 0. Si especifica solo el registro en tiempo real y también proporciona un desplazamiento con un nombre de archivo de registro válido, ETW usará el nombre del archivo de registro para crear un archivo de registro secuencial y eventos de registro en el archivo de registro, además de enviar los eventos a los consumidores en tiempo real. ETW también crea el archivo de registro secuencial si LogFileMode es 0 y proporciona un desplazamiento con un nombre de archivo de registro válido.

Si desea registrar eventos en un archivo de registro, debe reservar suficiente memoria para que esta estructura incluya el nombre del archivo de registro y el nombre de sesión después de la estructura. El nombre del archivo de registro debe seguir el nombre de sesión en la memoria. Vea los comentarios para obtener un ejemplo.

Los archivos de seguimiento se crean con el descriptor de seguridad predeterminado, lo que significa que el archivo de registro tendrá la misma ACL que el directorio primario. Si desea acceder a los archivos restringidos, cree un directorio primario con las ACL adecuadas.

LoggerNameOffset

Desplazamiento (en bytes) desde el principio de la memoria asignada de la estructura al principio de la cadena terminada en nul que contiene el nombre de la sesión.

Importante

Use un nombre descriptivo para la sesión para que la propiedad y el uso de la sesión se puedan determinar a partir del nombre de la sesión. No use un GUID u otro valor no descriptivo. No anexe dígitos aleatorios para que el nombre de la sesión sea único. Las sesiones ETW son un recurso limitado, por lo que el componente no debe iniciar varias sesiones. Si la sesión del componente ya se está ejecutando cuando se inicia el componente, el componente debe limpiar la sesión huérfana en lugar de crear una segunda sesión.

El nombre de la sesión está limitado a 1024 caracteres. El nombre de sesión no distingue mayúsculas de minúsculas. El sistema no iniciará una nueva sesión si ya se está ejecutando otra sesión con el mismo nombre.

Windows 2000: Los nombres de sesión distinguen mayúsculas de minúsculas. Como resultado, solo se permiten sesiones con nombres diferentes en caso de que se permitan. Sin embargo, para reducir la confusión, debe asegurarse de que los nombres de sesión son únicos.

Comentarios

Al asignar la memoria para esta estructura, debe asignar suficiente memoria para incluir el nombre de sesión y el nombre del archivo de registro después de la estructura. El nombre de la sesión debe aparecer antes del nombre del archivo de registro en la memoria. Debe copiar el nombre del archivo de registro en el desplazamiento, pero no copia el nombre de la sesión en el desplazamiento. La función StartTrace copia automáticamente el nombre.

Asegúrese de inicializar la memoria de esta estructura en cero antes de establecer los miembros. Por ejemplo:

typedef struct EventTracePropertyData {
    EVENT_TRACE_PROPERTIES Props;
    WCHAR LoggerName[128];
    WCHAR LogFileName[1024];
} EventTracePropertyData;

EventTracePropertyData data = {0};
data.Props.Wnode.BufferSize = sizeof(data);
data.Props.Wnode.Flags = WNODE_FLAG_TRACED_GUID;
data.Props.LogFileNameOffset = offsetof(EventTracePropertyData, LogFileName);
data.Props.LoggerNameOffset = offsetof(EventTracePropertyData, LoggerName);

Los eventos de los proveedores se escriben en los búferes de una sesión. Cuando un búfer de un archivo o una sesión en tiempo real está lleno (o cuando expira FlushTimer), la sesión vacía el búfer escribiendo los eventos en un archivo de registro, entregándolos a un consumidor en tiempo real o ambos. Si los búferes de una sesión se rellenan más rápido de lo que se pueden vaciar, se asignan nuevos búferes y se agregan al grupo de búferes de la sesión, hasta MaximumBuffers. Más allá de este límite, la sesión descarta los eventos entrantes hasta que un búfer esté disponible. Cada sesión mantiene un registro del número de eventos descartados (vea el miembro EventsLost ).

Para ver las estadísticas de sesión, como EventsLost mientras se ejecuta la sesión, llame a la función ControlTrace y establezca el parámetro ControlCode en EVENT_TRACE_CONTROL_QUERY.

Requisitos

Cliente mínimo compatible	Windows 2000 Professional [aplicaciones de escritorio | Aplicaciones para UWP]
Servidor mínimo compatible	Windows 2000 Server [aplicaciones de escritorio | Aplicaciones para UWP]
Encabezado	evntrace.h

Consulte también

StartTrace

ControlTrace

QueryAllTraces

Constantes del modo de registro

EVENT_TRACE_PROPERTIES_V2

WNODE_HEADER