Compartir a través de


estructura EVENT_TRACE_LOGFILEA (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 de 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 el 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_LOGFILEA {
  LPSTR                         LogFileName;
  LPSTR                         LoggerName;
  LONGLONG                      CurrentTime;
  ULONG                         BuffersRead;
  union {
    ULONG LogFileMode;
    ULONG ProcessTraceMode;
  } DUMMYUNIONNAME;
  EVENT_TRACE                   CurrentEvent;
  TRACE_LOGFILE_HEADER          LogfileHeader;
  PEVENT_TRACE_BUFFER_CALLBACKA BufferCallback;
  ULONG                         BufferSize;
  ULONG                         Filled;
  ULONG                         EventsLost;
  union {
    PEVENT_CALLBACK        EventCallback;
    PEVENT_RECORD_CALLBACK EventRecordCallback;
  } DUMMYUNIONNAME2;
  ULONG                         IsKernelTrace;
  PVOID                         Context;
} EVENT_TRACE_LOGFILEA, *PEVENT_TRACE_LOGFILEA;

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 registra 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 id. mytrace.etl_123de proceso, por ejemplo, . 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 timeStamp del evento a partir 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 convertir en 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 de 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 de ETW de 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 de ProcessTrace, compruebe que el campo ProcessTraceMode no incluye la PROCESS_TRACE_MODE_EVENT_RECORD marca.

Sugerencia

El código nuevo 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 garbleados 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 de EVENT_RECORD en este valor.

Antes de Windows Vista: No se admite.

Comentarios

Los consumidores de eventos deben:

  1. Inicialice la memoria de esta estructura en cero.
  2. 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.
  3. 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_RECORD a 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.
  4. 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.
  5. Si desea los datos de marca de tiempo sin procesar originales en lugar de la marca de tiempo procesada, agregue PROCESS_TRACE_MODE_RAW_TIMESTAMP a ProcessTraceMode.
  6. 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.
  7. 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.
  8. 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 neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos

   
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

Consulte también

BufferCallback

EventRecordCallback

OpenTrace