Función ControlTraceW (evntrace.h)

La función ControlTrace vacía, consulta, actualizaciones o detiene la sesión de seguimiento de eventos especificada.

Sintaxis

ULONG WMIAPI ControlTraceW(
  [in]      TRACEHANDLE             TraceHandle,
  [in]      LPCWSTR                 InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties,
  [in]      ULONG                   ControlCode
);

Parámetros

[in] TraceHandle

Controle una sesión de seguimiento de eventos o 0. Debe especificar un traceHandle distinto de cero si InstanceName es NULL. ETW omite el identificador si InstanceName no es NULL.

La función StartTrace devuelve este identificador cuando se inicia un nuevo seguimiento. Para obtener el identificador de un seguimiento existente, use ControlTrace para consultar las propiedades de seguimiento en función del nombre del seguimiento y, a continuación, obtener el identificador del campo Wnode.HistoricalContext de los datos devueltos EVENT_TRACE_PROPERTIES .

[in] InstanceName

Nombre de una sesión de seguimiento de eventos o NULL. Debe especificar InstanceName si TraceHandle es 0.

Para especificar la sesión del registrador de kernel nt, establezca InstanceNameen KERNEL_LOGGER_NAME.

[in, out] Properties

Puntero a una estructura de EVENT_TRACE_PROPERTIES inicializada. Esta estructura debe ser cero antes de establecer cualquier campo.

Si ControlCode especifica EVENT_TRACE_CONTROL_STOP, EVENT_TRACE_CONTROL_QUERY o EVENT_TRACE_CONTROL_FLUSH, solo tiene que establecer los miembros Wnode.BufferSize, Wnode.Guid, LoggerNameOffset y LogFileNameOffset de la estructura EVENT_TRACE_PROPERTIES . Si la sesión es una sesión privada, también debe establecer LogFileMode. Puede usar el nombre de sesión máximo (1024 caracteres) y las longitudes máximas de nombre de archivo de registro (1024 caracteres) para calcular el tamaño y los desplazamientos del búfer si no se conocen.

Si ControlCode especifica EVENT_TRACE_CONTROL_UPDATE, en la entrada, los miembros deben especificar los nuevos valores para que se actualicen las propiedades. En la salida, Properties contiene las propiedades y estadísticas de la sesión de seguimiento de eventos. Puede actualizar las siguientes propiedades.

• EnableFlags: establezca este miembro en 0 para deshabilitar todos los proveedores del sistema. Establézcalo en un valor distinto de cero para especificar los proveedores del sistema que desea habilitar o mantener habilitados. Esto puede ser distinto de cero solo para los registradores del sistema.

• FlushTimer: establezca este miembro si desea cambiar el tiempo de espera antes de vaciar los búferes. Si este miembro es 0, el miembro no se actualiza.

• LogFileNameOffset: establezca este miembro si desea cambiar a otro archivo de registro o para vaciar un seguimiento en modo de almacenamiento en búfer en un nuevo archivo de registro. Si este miembro es 0, el nombre de archivo no se actualiza. Si el desplazamiento no es cero y no cambia el nombre del archivo de registro, la función devuelve un error.

• LogFileMode: establezca este miembro si desea activar y desactivar EVENT_TRACE_REAL_TIME_MODE . Para desactivar el tiempo real, establezca este miembro en 0. Para activar el tiempo real (crear una sesión que registra en disco, así como entregar eventos en tiempo real), establezca este miembro en EVENT_TRACE_REAL_TIME_MODE y será OR con los modos actuales.

• MaximumBuffers: establezca este miembro si desea cambiar el número máximo de búferes que usa ETW. Si este miembro es 0, el miembro no se actualiza.

En el caso de las sesiones de registrador privados, solo puede actualizar los miembros LogFileNameOffset y FlushTimer .

Si usa una estructura de EVENT_TRACE_PROPERTIES recién inicializada, agote la estructura, establezca Wnode.BufferSize, Wnode.Guid y Wnode.Flags y los valores que desee actualizar.

Si va a reutilizar una estructura de EVENT_TRACE_PROPERTIES (es decir, mediante una estructura que anteriormente pasó a StartTrace o ControlTrace), asegúrese de establecer el miembro LogFileNameOffset en 0 a menos que cambie el nombre del archivo de registro y asegúrese de establecer EVENT_TRACE_PROPERTIES. Wnode.Flags para WNODE_FLAG_TRACED_GUID.

A partir de Windows 10, versión 1703: Para mejorar el rendimiento en escenarios entre procesos, ahora puede pasar información de filtrado a ControlTrace para registradores privados de todo el sistema. Deberá usar la estructura EVENT_TRACE_PROPERTIES_V2 para incluir información de filtrado. Consulte Configuración e inicio de una sesión de registrador privado para obtener más información.

[in] ControlCode

Función de control solicitada. Puede especificar uno de los siguientes valores:

• EVENT_TRACE_CONTROL_FLUSH: vacía los búferes activos de la sesión.

  Esto se puede usar con una sesión en memoria (una sesión iniciada con la marca de EVENT_TRACE_BUFFERING_MODE ) para escribir los datos del seguimiento en un archivo.

  Normalmente no es necesario vaciar las sesiones basadas en archivos o en tiempo real, ya que ETW vaciará automáticamente un búfer cuando esté lleno (es decir, cuando no tenga espacio para el siguiente evento), cuando expire el FlushTimer de la sesión de seguimiento o cuando se cierre la sesión de seguimiento.

  Windows 2000: Este valor no se admite.

• EVENT_TRACE_CONTROL_QUERY: recupera las estadísticas y las propiedades de la sesión.

• EVENT_TRACE_CONTROL_STOP: detiene la sesión. El identificador de sesión ya no es válido.

• EVENT_TRACE_CONTROL_UPDATE: Novedades las propiedades de la sesión.

• EVENT_TRACE_CONTROL_INCREMENT_FILE: si la sesión tiene , EVENT_TRACE_FILE_MODE_NEWFILEactualiza la sesión para cambiar al siguiente archivo inmediatamente, en lugar de esperar a que se rellene el archivo anterior. Se admite a partir de la actualización de octubre de 2018 de Windows 10.

• EVENT_TRACE_CONTROL_CONVERT_TO_REALTIME: cambia una sesión en modo de archivo a una sesión en tiempo real (habilita la entrega en tiempo real y deshabilita la escritura de eventos en el archivo ETL). Se admite a partir de la actualización de octubre de 2020 de Windows 10.

Nota

No es seguro vaciar los búferes ni detener una sesión de seguimiento de DllMain (puede provocar interbloqueo).

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es ERROR_SUCCESS.

Si se produce un error en la función, el valor devuelto es uno de los códigos de error del sistema. A continuación se muestran algunos errores comunes y sus causas.

• ERROR_BAD_LENGTH

  Una de las siguientes condiciones se cumple:

  • El miembro Wnode.BufferSize de Properties especifica un tamaño incorrecto.
  • Las propiedades no tienen espacio suficiente asignado para contener una copia del nombre de la sesión y el nombre del archivo de registro (si se usa).

• ERROR_INVALID_PARAMETER

  Una de las siguientes condiciones se cumple:

  • Las propiedades son NULL.
  • InstanceName y TraceHandle son NULL.
  • InstanceName es NULL y TraceHandle no es un identificador válido.
  • El miembro LogFileNameOffset de Properties no es válido.
  • El miembro LoggerNameOffset de Properties no es válido.
  • El miembro LogFileMode de Properties especifica una combinación de marcas que no son válidas.
  • El miembro Wnode.Guid de Properties es SystemTraceControlGuid, pero el parámetro InstanceName no KERNEL_LOGGER_NAMEes .

• ERROR_BAD_PATHNAME

  Otra sesión ya usa el nombre de archivo especificado por el miembro LogFileNameOffset de la estructura Properties .

• ERROR_MORE_DATA

  El búfer de EVENT_TRACE_PROPERTIES es demasiado pequeño para contener toda la información de la sesión. Si no necesita la información de propiedad de la sesión, puede omitir este error. Si recibe este error al detener la sesión, ETW ya habrá detenido la sesión antes de generar este error.

• ERROR_ACCESS_DENIED

  Solo los usuarios que se ejecutan con privilegios administrativos elevados, los usuarios del grupo Usuarios del registro de rendimiento y los servicios que se ejecutan como LocalSystem, LocalService, NetworkService pueden controlar las sesiones de seguimiento de eventos. Para conceder a un usuario restringido la capacidad de controlar las sesiones de seguimiento, agréguelas al grupo Usuarios del registro de rendimiento. Solo los usuarios con privilegios administrativos y servicios que se ejecutan como LocalSystem pueden controlar una sesión de registrador de kernel de NT.

  Windows XP y Windows 2000: Cualquier persona puede controlar una sesión de seguimiento.

• ERROR_WMI_INSTANCE_NOT_FOUND

  La sesión especificada no se está ejecutando.

• ERROR_ACTIVE_CONNECTIONS

  Cuando se devuelve desde una llamada EVENT_TRACE_CONTROL_STOP, esto indica que la sesión ya está en proceso de detención.

Comentarios

Los controladores de seguimiento de eventos llaman a esta función.

Esta función sustituye a las funciones FlushTrace, QueryTrace, StopTrace y UpdateTrace .

Nota:

El encabezado evntrace.h define ControlTrace 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 [aplicaciones de escritorio | Aplicaciones para UWP]
Servidor mínimo compatible	Windows 2000 Server [aplicaciones de escritorio | Aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	evntrace.h
Library	Sechost.lib en Windows 8.1 y Windows Server 2012 R2; Advapi32.lib en Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista y Windows XP
Archivo DLL	Sechost.dll en Windows 8.1 y Windows Server 2012; Advapi32.dll en Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista y Windows XP

Consulte también

EVENT_TRACE_PROPERTIES

QueryAllTraces

StartTrace