Función StartTraceA (evntrace.h)

  • Artículo

La función StartTrace registra e inicia una sesión de seguimiento de eventos.

Importante

Las sesiones de seguimiento de eventos entre procesos son un recurso del sistema limitado. Los desarrolladores deben evitar iniciar sesiones de seguimiento de eventos en las máquinas del cliente. Cuando se necesiten sesiones de seguimiento de eventos, deben limitarse al ámbito más pequeño posible: use lo menos sesiones posibles, use una sesión solo en proceso si es posible (EVENT_TRACE_PRIVATE_LOGGER_MODE | EVENT_TRACE_PRIVATE_IN_PROC), inicie solo el seguimiento cuando se necesite específicamente la recopilación para un escenario, detenga el seguimiento tan pronto como se complete el escenario, limite la cantidad de memoria usada por la sesión, y usan filtros de eventos estrictos para que no recopile eventos innecesarios.

Sintaxis

ULONG WMIAPI StartTraceA(
  [out]     PTRACEHANDLE            TraceHandle,
  [in]      LPCSTR                  InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties
);

Parámetros

[out] TraceHandle

Recibe el identificador de la sesión de seguimiento de eventos para su uso posterior con api como ControlTrace.

No use este identificador si se produce un error en la función. No compare el identificador de sesión con INVALID_HANDLE_VALUE. El identificador de sesión es 0 si el identificador no es válido.

[in] InstanceName

Cadena terminada en NULL que contiene el nombre de la sesión de seguimiento de eventos. El nombre de la sesión está limitado a 1024 caracteres, no distingue mayúsculas de minúsculas y debe ser único.

Importante

Use un nombre descriptivo para la sesión para que la propiedad y el uso de la sesión se puedan determinar a partir del nombre de la sesión. No use un GUID u otro valor no determinista o no descriptivo. No anexe dígitos aleatorios para que el nombre de la sesión sea único. Las sesiones ETW son un recurso limitado, por lo que el componente no debe iniciar varias sesiones. Si la sesión del componente ya se está ejecutando cuando se inicia el componente, el componente debe limpiar la sesión huérfana en lugar de crear una segunda sesión.

Esta función copia el nombre de sesión al que se proporciona el desplazamiento al que apunta el miembro LoggerNameOffset de Properties .

[in, out] Properties

Puntero a una estructura de EVENT_TRACE_PROPERTIES que especifica el comportamiento de la sesión. A continuación se muestran los miembros clave de la estructura que se van a establecer:

  • Wnode.BufferSize
  • Wnode.Guid
  • Wnode.ClientContext
  • Wnode.Flags
  • LogFileMode
  • LogFileNameOffset
  • LoggerNameOffset

En función del tipo de archivo de registro que elija crear, es posible que también tenga que especificar un valor para MaximumFileSize. Consulte la sección Comentarios para obtener más información sobre cómo establecer el parámetro Properties y el comportamiento de la sesión.

A partir de Windows 10, versión 1703: para mejorar el rendimiento en escenarios entre procesos, ahora puede pasar el filtrado a StartTrace al iniciar registradores privados de todo el sistema. Deberá pasar la nueva estructura de 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.

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 de InstanceName.

  • ERROR_INVALID_PARAMETER

    Una de las siguientes condiciones se cumple:

    • Las propiedades son NULL.
    • TraceHandle es NULL.
    • 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 es SystemTraceControlGuid, pero el parámetro InstanceName no es KERNEL_LOGGER_NAME.

  • ERROR_ALREADY_EXISTS

    Ya se está ejecutando una sesión con el mismo nombre o GUID.

  • ERROR_BAD_PATHNAME

    Puede recibir este error por uno de los siguientes motivos:

    • Otra sesión ya usa el nombre de archivo especificado por el miembro LogFileNameOffset de la estructura Properties .
    • LogFileMode y LogFileNameOffset son cero.

  • ERROR_DISK_FULL

    No hay suficiente espacio disponible en la unidad para el archivo de registro. Esto ocurre si:

    • MaximumFileSize es distinto de cero y no hay bytes MaximumFileSize disponibles para el archivo de registro.
    • la unidad es una unidad del sistema y no hay más de 200 MB disponibles.
    • MaximumFileSize es cero y no hay más de 200 MB disponibles

    Elija una unidad con más espacio o reduzca el tamaño especificado en MaximumFileSize (si se usa).

  • ERROR_ACCESS_DENIED

    Solo los usuarios con privilegios administrativos, 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.

    Si el usuario es miembro del grupo Usuarios del registro de rendimiento, es posible que no tenga permiso para crear el archivo de registro en la carpeta especificada.

  • ERROR_NO_SYSTEM_RESOURCES

    Una de las siguientes condiciones se cumple:

    • La sesión de registro usa la marca EVENT_TRACE_SYSTEM_LOGGER_MODE y se ha alcanzado el número máximo de registradores del sistema (8).

    • Se ha alcanzado el número máximo de sesiones de registro en el sistema. No se puede crear ningún registrador nuevo hasta que se haya detenido una sesión de registro. En la mayoría de los sistemas, el número máximo de sesiones de registro es 64.

      Puede cambiar el número máximo de sesiones de registro de un sistema editando la clave de REG_DWORD en HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\WMI@EtwMaxLoggers. Los valores permitidos son de 32 a 256, ambos incluidos. Se requiere un reinicio para que cualquier cambio surta efecto.

      Tenga en cuenta que los registradores usan recursos del sistema. Aumentar el número de registradores en el sistema tendrá un costo de rendimiento si se rellenan esas ranuras. Este límite existe para evitar el uso excesivo de recursos del sistema.

      Importante

      El límite solo debe ajustarse manualmente un administrador del sistema para habilitar escenarios específicos. El valor EtwMaxLoggers no debe modificarse automáticamente mediante un programa o controlador.

      Antes de Windows 10, versión 1709, se trata de un límite fijo de 64 registradores para registradores no privados.

Comentarios

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

La sesión permanece activa hasta que se detiene la sesión, se reinicia el equipo, se produce un error de E/S o se alcanza el tamaño máximo del archivo para los registros no circulares. Para detener una sesión de seguimiento de eventos, llame a la función ControlTrace y establezca el parámetro ControlCode en EVENT_TRACE_CONTROL_STOP.

No se puede iniciar más de una sesión con el mismo GUID de sesión (especificado por Properties.Wnode.Guid). En la mayoría de los casos, se establecerá Properties.Wnode.Guid en all-zero (es decir , GUID_NULL) para permitir que el sistema ETW genere un nuevo GUID para la sesión.

Para especificar una sesión de registrador privado, establezca el miembro Wnode.Guid de Propiedades en el GUID de control del proveedor, no en el GUID de control de la sesión del registrador privado. El proveedor debe haber registrado el GUID antes de llamar a StartTrace.

Esta función no se usa para iniciar una sesión de registrador global (en desuso). Para obtener más información sobre cómo iniciar una sesión de registrador global, consulte Configuración e inicio de la sesión del registrador global.

Registradores del sistema

Para que el registrador sea un registrador del sistema y reciba eventos de SystemTraceProvider u otros proveedores del sistema, cualquiera de los siguientes debe ser true:

  • El miembro PropertiesLogFileMode incluye la marca EVENT_TRACE_SYSTEM_LOGGER_MODE (preferida).
  • El miembro PropertiesWnode.Guid se establece en SystemTraceControlGuid o GlobalLoggerGuid (en desuso, no se debe usar para el nuevo código porque entrará en conflicto con otros componentes que también intentan usar estos GUID).
  • InstanceName se establece en KERNEL_LOGGER_NAME (en desuso: no se debe usar para el nuevo código porque entra en conflicto con otros componentes que también intentan usar este nombre).

Nota

 Un registrador del sistema debe establecer el miembro EnableFlags de la estructura EVENT_TRACE_PROPERTIES para indicar qué eventos SystemTraceProvider deben incluirse en el seguimiento.

Dado que los registradores del sistema reciben eventos de kernel especiales, están sujetos a restricciones adicionales:

  • No puede haber más de 8 registradores del sistema activos en el mismo sistema.
  • Los registradores del sistema no se pueden crear en un contenedor de Windows Server.
  • Los registradores del sistema no pueden usar la marca EVENT_TRACE_USE_PAGED_MEMORY .
  • Antes de Windows 10, versión 1703, cualquier registrador del sistema puede usar simultáneamente más de 2 tipos de reloj distintos. Por ejemplo, si un registrador activo del sistema usa el tipo de reloj "Contador de ciclo de CPU" y otro registrador del sistema activo usa el tipo de reloj "Contador de rendimiento de consultas", se producirá un error en cualquier intento de iniciar un registrador del sistema mediante el tipo de reloj "Hora del sistema" porque requeriría la activación de un tercer tipo de reloj. Debido a esta limitación, Microsoft recomienda encarecidamente que los registradores del sistema no usen el tipo de reloj "Hora del sistema".
  • A partir de Windows 10, versión 1703, se ha quitado la restricción de tipo de reloj. Los registradores del sistema ahora pueden usar los tres tipos de reloj simultáneamente.

Para especificar una sesión de registrador de kernel nt (en desuso), establezca InstanceName en KERNEL_LOGGER_NAME y el miembro Wnode.Guid de Propiedades en SystemTraceControlGuid. Si no especifica el GUID como SystemTraceControlGuid, ETW invalidará el valor guid y lo establecerá en SystemTraceControlGuid.

Ejemplos

Para obtener un ejemplo que usa StartTrace, consulte Configuración e inicio de una sesión de seguimiento de eventos.

Nota

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

Consulte también

ControlTrace

EVENT_TRACE_PROPERTIES