estructura EVENT_TRACE_LOGFILEW (evntrace.h)
La estructura EVENT_TRACE_LOGFILE almacena información sobre un origen de datos de seguimiento.
La estructura EVENT_TRACE_LOGFILE se usa al llamar a OpenTrace. El usuario proporciona una estructura EVENT_TRACE_LOGFILE con información sobre el origen de datos de seguimiento (el nombre de un archivo ETL o el nombre de una sesión activa del registrador en tiempo real), las marcas de procesamiento de seguimiento y las funciones de devolución de llamada que recibirán datos de seguimiento. Si se ejecuta correctamente, OpenTrace rellena los campos restantes de la estructura para devolver detalles sobre el origen de datos de seguimiento.
Cuando ProcessTrace procesa un búfer, invoca bufferCallback definido por el usuario con una estructura de EVENT_TRACE_LOGFILE para proporcionar información sobre la sesión de procesamiento de eventos y el búfer.
Sintaxis
typedef struct _EVENT_TRACE_LOGFILEW {
LPWSTR LogFileName;
LPWSTR LoggerName;
LONGLONG CurrentTime;
ULONG BuffersRead;
union {
ULONG LogFileMode;
ULONG ProcessTraceMode;
} DUMMYUNIONNAME;
EVENT_TRACE CurrentEvent;
TRACE_LOGFILE_HEADER LogfileHeader;
PEVENT_TRACE_BUFFER_CALLBACKW BufferCallback;
ULONG BufferSize;
ULONG Filled;
ULONG EventsLost;
union {
PEVENT_CALLBACK EventCallback;
PEVENT_RECORD_CALLBACK EventRecordCallback;
} DUMMYUNIONNAME2;
ULONG IsKernelTrace;
PVOID Context;
} EVENT_TRACE_LOGFILEW, *PEVENT_TRACE_LOGFILEW;
Miembros
LogFileName
Nombre del archivo de registro que se está procesando o NULL si procesa datos de una sesión de seguimiento en tiempo real. Especifique un valor para este miembro si llama a OpenTrace para consumir datos de un archivo de registro.
Al llamar a OpenTrace, si LoggerName no es NULL , LogFileName debe ser NULL.
Al llamar a OpenTrace, el usuario que consume los eventos debe tener permisos para leer el archivo.
Nota
El nombre de archivo proporcionado a OpenTrace a través del campo LogFileName debe ser el nombre de archivo completo, incluidos los sufijos. Algunas API de creación de archivos de seguimiento pueden agregar silenciosamente un sufijo al nombre de archivo especificado por el usuario. Por ejemplo, si el controlador registró eventos en una sesión privada (el controlador establece el miembro LogFileMode de EVENT_TRACE_PROPERTIES en EVENT_TRACE_PRIVATE_LOGGER_MODE al llamar a StartTrace), el archivo ETL generado incluirá un sufijo de identificador de proceso, por ejemplo mytrace.etl_123, .
Esto también puede ocurrir si el archivo se creó con el modo EVENT_TRACE_FILE_MODE_NEWFILE , en cuyo caso el archivo ETL generado incluirá un número de secuencia.
LoggerName
Nombre de la sesión de seguimiento de eventos en tiempo real o NULL si procesa datos de un archivo de registro. Especifique un valor para este miembro si llama a OpenTrace para consumir datos de una sesión en tiempo real.
Al llamar a OpenTrace, si LogFileName no es NULL , LoggerName debe ser NULL.
Solo puede consumir eventos en tiempo real si el controlador de seguimiento ha establecido el miembro LogFileMode de EVENT_TRACE_PROPERTIES para incluir la marca EVENT_TRACE_REAL_TIME_MODE .
Solo los usuarios con privilegios administrativos, los usuarios del grupo Usuarios del registro de rendimiento y las aplicaciones que se ejecutan como LocalSystem, LocalService, NetworkService pueden consumir eventos en tiempo real. Para conceder a un usuario restringido la capacidad de consumir eventos en tiempo real, agréguelos al grupo Usuarios del registro de rendimiento o llame a EventAccessControl.
Windows XP y Windows 2000: Cualquier persona puede consumir eventos en tiempo real.
CurrentTime
En la salida, la hora actual, en intervalos de 100 nanosegundos desde medianoche, 1 de enero de 1601.
BuffersRead
En la salida, el número de búferes procesados.
DUMMYUNIONNAME
DUMMYUNIONNAME.LogFileMode
Reservado. No utilizar.
DUMMYUNIONNAME.ProcessTraceMode
Modos de procesamiento de eventos. Los modos se definen en el archivo de evntcons.h encabezado. Puede especificar uno o varios de los modos siguientes:
PROCESS_TRACE_MODE_EVENT_RECORD
Especifique este modo si desea recibir eventos en el nuevo formato de EVENT_RECORD (se recomienda encarecidamente). Para recibir eventos en el nuevo formato, debe especificar una devolución de llamada en el miembro EventRecordCallback . Si no especifica este modo, recibirá eventos en el formato anterior a través de la devolución de llamada especificada en el miembro EventCallback .
Antes de Windows Vista: No se admite.
PROCESS_TRACE_MODE_RAW_TIMESTAMP
De forma predeterminada, ProcessTrace convierte el TimeStamp del evento del formato sin procesar original (tiempo del sistema, tiempo de QPC o contador de ciclo de CPU) en tiempo del sistema (intervalos de 100 nanosegundos desde la medianoche, 1 de enero de 1601).
Especifique la marca PROCESS_TRACE_MODE_RAW_TIMESTAMP si no desea el valor de marca de tiempo en el miembro TimeStamp de EVENT_HEADER y EVENT_TRACE_HEADER convertido a la hora del sistema. Si se especifica esta marca, ProcessTrace dejará el valor de marca de tiempo en el formato original que el controlador especificó en el miembro Wnode.ClientContext de EVENT_TRACE_PROPERTIES.
Antes de Windows Vista: No se admite.
PROCESS_TRACE_MODE_REAL_TIME
Especifique este modo para recibir eventos en tiempo real. Debe especificar este modo si LoggerName no es NULL.
CurrentEvent
En la salida, una estructura EVENT_TRACE que contiene el último evento procesado.
LogfileHeader
En la salida, una estructura de TRACE_LOGFILE_HEADER que contiene información general sobre la sesión y el equipo en el que se ejecutó la sesión.
BufferCallback
Puntero a la función BufferCallback que recibe estadísticas relacionadas con el búfer para cada vaciado ETW del búfer. ETW llama a esta devolución de llamada después de que entregue todos los eventos del búfer. Esta devolución de llamada es opcional.
BufferSize
En la salida, contiene el tamaño de cada búfer, en bytes.
Filled
En la salida, contiene el número de bytes en el búfer que contienen información válida.
EventsLost
No se usa.
DUMMYUNIONNAME2
DUMMYUNIONNAME2.EventCallback
Puntero a la función EventCallback que ETW llama a para cada evento del búfer. Este campo solo se usa si el campo ProcessTraceMode no incluye la PROCESS_TRACE_MODE_EVENT_RECORD marca .
Nota
El campo EventCallback se tratará como eventRecordCallback si el campo ProcessTraceMode incluye la PROCESS_TRACE_MODE_EVENT_RECORD marca. Si EventCallback recibe datos en garancha de ProcessTrace, compruebe que el campo ProcessTraceMode no incluye la PROCESS_TRACE_MODE_EVENT_RECORD marca .
Sugerencia
El nuevo código debe usar EventRecordCallback en lugar de EventCallback. EventRecordCallback recibe un EVENT_RECORD que contiene información de eventos más completa, se puede usar con api de descodificación como TdhGetEventInformation y tiene un puntero de contexto que puede usar la devolución de llamada.
DUMMYUNIONNAME2.EventRecordCallback
Puntero a la función EventRecordCallback que ETW llama a para cada evento del búfer. Este campo solo se usa si el campo ProcessTraceMode incluye la PROCESS_TRACE_MODE_EVENT_RECORD marca .
Nota
El campo EventRecordCallback se tratará como eventCallback si el campo ProcessTraceMode no incluye la PROCESS_TRACE_MODE_EVENT_RECORD marca . Si eventRecordCallback recibe datos garblemados de ProcessTrace, compruebe que el campo ProcessTraceMode incluye la PROCESS_TRACE_MODE_EVENT_RECORD marca .
Antes de Windows Vista: No se admite.
IsKernelTrace
En la salida, si este miembro es TRUE, la sesión de seguimiento de eventos es el registrador de kernel nt. De lo contrario, es otra sesión de seguimiento de eventos.
Context
Datos de contexto que un consumidor puede especificar al llamar a OpenTrace. Si el consumidor usa EventRecordCallback para consumir eventos, ETW establece el miembro UserContext de la estructura EVENT_RECORD en este valor.
Antes de Windows Vista: No se admite.
Comentarios
Los consumidores de eventos deben:
- Inicialice la memoria de esta estructura en cero.
- Si lee desde un archivo ETL, establezca LogFileName en la ruta de acceso al archivo.
De lo contrario (es decir, si lee desde una sesión en tiempo real), establezca LoggerName en el nombre de la sesión y establezca ProcessTraceMode en
PROCESS_TRACE_MODE_REAL_TIME. - Si usa EventRecordCallback (recomendado), establezca EventRecordCallback en la dirección de la función de devolución de llamada del registro de eventos, establezca Context en un valor que se proporcionará a la devolución de llamada y agregue
PROCESS_TRACE_MODE_EVENT_RECORDa ProcessTraceMode. De lo contrario (es decir, si usa EventCallback), establezca EventCallback en la dirección de la función de devolución de llamada del evento. - Si necesita una devolución de llamada después de procesar cada búfer, establezca BufferCallback en la dirección de la función de devolución de llamada del búfer.
- Si desea los datos de marca de tiempo sin procesar originales en lugar de la marca de tiempo procesada, agregue
PROCESS_TRACE_MODE_RAW_TIMESTAMPa ProcessTraceMode. - Llame a OpenTrace. Tenga en cuenta que, si se ejecuta correctamente, la función OpenTrace rellenará los miembros de esta estructura con información del origen de datos de seguimiento.
- Llame a ProcessTrace con el identificador devuelto por OpenTrace.
- ProcessTrace invocará la función de devolución de llamada de eventos para cada evento.
- ProcessTrace invocará la función de devolución de llamada del búfer (si se proporciona) después de finalizar cada búfer e incluirá una instancia de la estructura de EVENT_TRACE_LOGFILE con información de estado de procesamiento de seguimiento.
- Una vez completado el procesamiento de seguimiento, llame a CloseTrace para cerrar el identificador devuelto por OpenTrace.
Nota
El encabezado evntrace.h define EVENT_TRACE_LOGFILE como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows 2000 Professional [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows 2000 Server [solo aplicaciones de escritorio] |
| Encabezado | evntrace.h |