StartKernelTrace
Esta función registra e inicia una sesión de seguimiento de eventos de kernel. También puede habilitar stackwalking para determinados eventos de kernel mediante esta función.
ULONG
WINAPI
StartKernelTrace(
__out PTRACEHANDLE TraceHandle,
__inout PEVENT_TRACE_PROPERTIES Properties,
__in ULONG cStackTracingEventIds
);
Parámetros
TraceHandle [out]
Almacena un identificador en una sesión de seguimiento de eventos. Este parámetro se establece en cero si el identificador no es válido. Este parámetro no debe compararse con INVALID_HANDLE_VALUE. No use este identificador si se produce un error en la función.
Propiedades [in, out]
Almacena un puntero a una estructura de EVENT_TRACE_PROPERTIES. EVENT_TRACE_PROPERTIES configura ciertos aspectos del comportamiento de la sesión.
El primer miembro de la estructura EVENT_TRACE_PROPERTIES es una estructura WNODE_HEADER, denominada aquí Wnode.
El siguiente EVENT_TRACE_PROPERTIES. Los miembros de Wnode deben establecerse para configurar el control de seguimiento del kernel.
BufferSize
Este miembro contiene el tamaño total, en bytes, de la memoria asignada para las propiedades de la sesión de seguimiento de eventos. El tamaño de la memoria debe incluir suficiente espacio para almacenar los datos siguientes:
Estructura EVENT_TRACE_PROPERTIES.
Cadena de nombre de sesión.
Cadena de nombre de archivo de registro.
Guid
Cada sesión de seguimiento debe tener un GUID definido para hacer referencia a la sesión.
Para una sesión del registrador de kernel NT, este miembro debe establecerse en SystemTraceControlGuid. Para obtener más información sobre las constantes del modo de registro, vea Constantes del registrador de kernel nt.
ClientContext
Este miembro establece la resolución del reloj que se usa cuando se calcula la marca de tiempo de registro para cada evento. El valor predeterminado de este miembro es un contador de rendimiento de consultas.
Puede especificar uno de los siguientes valores:
1: Contador de rendimiento de consultas (QPC). El QPC proporciona una marca de tiempo de alta resolución (100 nanosegundos), pero es comparativamente más costosa para recuperar. Use esta resolución si tiene altas tasas de eventos o si el consumidor combina eventos de diferentes búferes. En equipos más antiguos, es posible que la marca de tiempo no sea precisa porque el contador a veces omite el reenvío debido a errores de hardware.
2: Hora del sistema. La hora del sistema proporciona una marca de tiempo de baja resolución (10 milisegundos), pero es comparativamente menos costosa para recuperar. Si el volumen de eventos es alto, es posible que la resolución del tiempo del sistema no sea lo suficientemente fina como para determinar la secuencia de eventos. En este caso, un conjunto de eventos tendrá la misma marca de tiempo, pero es posible que el orden en el que ETW entregue los eventos no sea correcto.
3: Contador de ciclo de CPU. El contador de CPU proporciona la marca de tiempo de mayor resolución y es el menos costoso para recuperar. Sin embargo, el contador de CPU no es confiable y no debe usarse en producción. Por ejemplo, en algunos equipos, el temporizador cambia la frecuencia debido a cambios térmicos y de energía, además de detener en algunos estados. Si el hardware no admite este tipo de reloj, ETW usa la hora del sistema. En Windows Server 2003, Windows XP con SP1 y Windows XP, este valor no se admite. Se introdujo en Windows Server 2003 con SP1 y Windows XP con SP2.
Banderas
Este miembro debe contener WNODE_FLAG_TRACED_GUID para indicar que la estructura contiene información de seguimiento de eventos y la información se envía a un registrador. WNODE_FLAG_TRACED_GUID se define en Evntrace.h.
También se deben establecer los siguientes EVENT_TRACE_PROPERTIES miembros:
LogFileMode
Indica qué modos de registro se van a usar en la sesión de seguimiento de eventos del kernel. Puede usar este miembro para especificar que los eventos se van a escribir en un archivo de registro, en un consumidor en tiempo real o en ambos.
Este miembro también se puede usar para especificar que la sesión es una sesión de registrador privado. Se pueden especificar uno o varios modos. Para obtener una lista de los modos posibles, consulte Constantes del modo de registro.
Nota No especifique el registro en tiempo real a menos que haya consumidores en tiempo real listos para consumir los eventos. Si no hay ningún consumidor en tiempo real, los eventos se escriben en un archivo de reproducción. El tamaño del archivo de reproducción es limitado. Si se alcanza el límite, no se registran nuevos eventos en el archivo de registro ni en el archivo de reproducción. Se produce un error en las funciones de registro con STATUS_LOG_FILE_FULL.
EnableFlags
Este miembro solo se usa para las sesiones del registrador de kernel NT. Identifica al registrador del kernel qué eventos se van a rastrear. Mediante or lógico, este miembro puede contener uno o varios valores. Además de los eventos especificados, el registrador del kernel también registra eventos de configuración de hardware.
Las siguientes marcas de control de seguimiento están disponibles además de las proporcionadas por EVENT_TRACE_PROPERTIES:
LogFileNameOffset
Este número representa el desplazamiento desde el inicio de la memoria asignada a la estructura al inicio de la cadena terminada en NULL que contiene el nombre del archivo de registro.
Se aplican las siguientes consideraciones:
La extensión de nombre de archivo debe ser .etl.
Todas las carpetas de la ruta de acceso deben existir.
La ruta de acceso puede ser relativa, absoluta, local o remota.
La ruta de acceso no debe contener variables de entorno, ya que esas variables no se expanden.
El usuario que inicia el seguimiento debe tener permiso de escritura 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 asignar suficiente memoria para incluir el identificador de proceso que se anexa al nombre de archivo para las sesiones de registrador privados y el número secuencial que se agrega a los archivos de registro creados mediante el nuevo modo de registro de archivos.
Si no desea registrar eventos en un archivo de registro (por ejemplo, solo especifica EVENT_TRACE_REAL_TIME_MODE), establezca LogFileNameOffset en cero. Si especifica solo el registro en tiempo real y también proporciona un desplazamiento con un nombre de archivo de registro válido, el nombre del archivo de registro se usa para crear un archivo de registro secuencial y eventos de registro en el archivo de registro. El archivo de registro secuencial también se crea si LogFileMode es cero y se proporciona un desplazamiento con un nombre de archivo de registro válido.
Si desea registrar eventos en un archivo de registro, debe asignar 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 la sesión en la memoria.
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 restringir el acceso a los archivos, cree un directorio primario con las ACL adecuadas.
LoggerNameOffset
Este miembro representa el desplazamiento desde el principio de la memoria asignada a la estructura hasta el inicio de la cadena terminada en null que contiene el nombre de la sesión.
Se aplican las siguientes consideraciones:
El nombre de la sesión está limitado a 1024 caracteres.
El nombre de la sesión no distingue mayúsculas de minúsculas y debe ser único.
Al asignar memoria para esta estructura, se debe reservar suficiente memoria para incluir el nombre de la 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. El nombre del archivo de registro debe copiarse en el área de desplazamiento. Esta función escribe el nombre de sesión definido por KERNEL_LOGGER_NAME.
Según el tipo de archivo de registro elegido, puede ser necesario establecer el miembro MaximumFileSize .
Nota No es necesario establecer el nombre del registrador en LoggerNameOffset porque esta función siempre usa el valor de KERNEL_LOGGER_NAME para llamar a StartKernelTrace. Esta función comprueba si Wnode.Guid corresponde a SystemTraceControlGuid; si no es así, devuelve ERROR_INVALID_PARAMETER. Si Wnode.Guid corresponde a KernelRundownGuid, se debe especificar el nombre del registrador. KernelRundownGuid es el GUID de control que se usa para registrar eventos como información de proceso existente, información de subprocesos, imágenes cargadas por proceso y configuración de hardware, como CPU, vídeo, disco, tarjetas de red, servicios, energía, Plug and Play y canales IDE de disco.
Valor devuelto
ERROR_SUCCESS indica que se ha realizado correctamente.
Los valores de error posibles se describen en la tabla siguiente.
| Valor de error | Descripción |
|---|---|
ERROR_ALREADY_EXISTS |
Solo se ejecuta una sola instancia del registrador de kernel en el sistema. Si esta función intenta iniciarse después de que otro componente haya iniciado el registro del kernel, es posible que se devuelva este error. |
ERROR_INVALID_FLAGS |
Posiblemente indica que hay marcas de seguimiento no válidas en Properties.EnableFlags. |
ERROR_OUT_OF_MEMORY |
Posiblemente indica un error al asignar memoria para EVENT_TRACE_PROPERTIES. |
Si se produce un error en la función por un motivo distinto de los enumerados, se devuelve un código de error del sistema.
Comentarios
Si StackTracingEventIds contiene eventos que no están habilitados en el EVENT_TRACE_PROPERTIES. El campo EnableFlags o no se pudo descodificar mediante el control de seguimiento del kernel, esas marcas se omiten y no se devuelve ningún código de error.
Requisitos:
Versiones: Disponible a partir de Windows Vista. Esta estructura se distribuye con Windows Analizador de rendimiento.
Encabezados: Declarado en KernelTraceControl.h. Incluya KernelTraceControl.h.
Biblioteca: Contenido en KernelTraceControl.dll.