Función ControlTraceA (evntrace.h)
La función ControlTrace vacía, consulta, actualizaciones o detiene la sesión de seguimiento de eventos especificada.
Sintaxis
ULONG WMIAPI ControlTraceA(
CONTROLTRACE_ID TraceId,
[in] LPCSTR InstanceName,
[in, out] PEVENT_TRACE_PROPERTIES Properties,
[in] ULONG ControlCode
);
Parámetros
TraceId
[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 de NT, establezca InstanceName en KERNEL_LOGGER_NAME.
[in, out] Properties
Puntero a una estructura de EVENT_TRACE_PROPERTIES inicializada. Esta estructura debe estar sin 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 las propiedades que se van a actualizar. 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 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 registre en el 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 privado, solo puede actualizar los miembros LogFileNameOffset y FlushTimer .
Si usa una estructura de EVENT_TRACE_PROPERTIES recién inicializada, cero fuera de la estructura, establezca Wnode.BufferSize, Wnode.Guid y Wnode.Flags y los valores que desea actualizar.
Si va a reutilizar una estructura de EVENT_TRACE_PROPERTIES (es decir, mediante una estructura que pasó anteriormente 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 en WNODE_FLAG_TRACED_GUID.
A partir de Windows 10, versión 1703: Para mejorar el rendimiento en escenarios de procesos cruzados, ahora puede pasar información de filtrado a ControlTrace para registradores privados en todo el sistema. Deberá usar la estructura EVENT_TRACE_PROPERTIES_V2 para incluir información de filtrado. Consulte Configuring and Starting a Private Logger Session (Configuración e inicio de una sesión de registrador privado ) para obtener más detalles.
[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 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 porque ETW vaciará automáticamente un búfer cuando esté lleno (es decir, cuando no tenga espacio para el evento siguiente), 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 propiedades y estadísticas 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: actualiza las propiedades de la sesión.
EVENT_TRACE_CONTROL_INCREMENT_FILE: si la sesión tiene
EVENT_TRACE_FILE_MODE_NEWFILE, actualiza 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 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 es válida.
- 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 la 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 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 del registrador de kernel 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.
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 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 [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 |