Función EnableTrace (evntrace.h)

Un controlador de sesión de seguimiento llama a EnableTrace para configurar cómo un proveedor de eventos ETW registra eventos en una sesión de seguimiento.

Esta función está obsoleta. La función EnableTraceEx2 reemplaza a esta función.

Sintaxis

ULONG WMIAPI EnableTrace(
  [in] ULONG       Enable,
  [in] ULONG       EnableFlag,
  [in] ULONG       EnableLevel,
  [in] LPCGUID     ControlGuid,
  [in] TRACEHANDLE TraceHandle
);

Parámetros

[in] Enable

Establézcalo en 1 para habilitar la recepción de eventos del proveedor o para ajustar la configuración utilizada al recibir eventos del proveedor (por ejemplo, para cambiar el nivel y las palabras clave). Establezca en 0 para deshabilitar la recepción de eventos del proveedor.

[in] EnableFlag

Máscara de bits de 32 bits de palabras clave que determinan las categorías de eventos que desea que escriba el proveedor. Normalmente, el proveedor escribe un evento si los bits de palabra clave del evento coinciden con cualquiera de los bits establecidos en este valor o si el evento no tiene ningún bit de palabra clave establecido, además de cumplir con el critera EnableLevel .

Nota

Los proveedores basados en EventRegister admiten palabras clave de 64 bits. Use EnableTraceEx2 para habilitar proveedores mediante una máscara MatchAnyKeyword de 64 bits.

[in] EnableLevel

Valor que indica el nivel máximo de eventos que desea que escriba el proveedor. Normalmente, el proveedor escribe un evento si el nivel del evento es menor o igual que este valor, además de cumplir los criterios EnableFlag .

Este valor debe estar en el intervalo de 1 a 255. Microsoft define la semántica de los niveles 1 a 5, como se muestra a continuación. Los valores inferiores indican eventos más graves. Cada valor de EnableLevel habilita el nivel especificado y todos los niveles más graves. Por ejemplo, si especifica TRACE_LEVEL_WARNING, el consumidor recibirá eventos de advertencia, error y crítico.

Valor	Significado
TRACE_LEVEL_CRITICAL (1)	Eventos de salida o finalización anómalos
TRACE_LEVEL_ERROR (2)	Eventos de error graves
TRACE_LEVEL_WARNING (3)	Eventos de advertencia, como errores de asignación
TRACE_LEVEL_INFORMATION (4)	Eventos informativos que no son de error
TRACE_LEVEL_VERBOSE (5)	Eventos de diagnóstico detallados

Las TRACE_LEVEL constantes se definen en evntrace.h. Las constantes equivalentes WINMETA_LEVEL se definen en winmeta.h.

[in] ControlGuid

GUID de control (id. de proveedor) del proveedor de eventos que desea habilitar o deshabilitar.

[in] TraceHandle

Identificador de la sesión de seguimiento de eventos para la que va a configurar el proveedor. 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 .

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_INVALID_PARAMETER

  Una de las siguientes condiciones se cumple:

  • ControlGuid es NULL.
  • TraceHandle es NULL.

• ERROR_INVALID_FUNCTION

  No se pueden cambiar las marcas de habilitación y el nivel cuando el proveedor no está registrado.

• ERROR_WMI_GUID_NOT_FOUND

  El proveedor no está registrado. Se produce cuando KB307331 o Windows 2000 Service Pack 4 está instalado y el proveedor no está registrado. Para evitar este error, primero se debe registrar el proveedor.

• ERROR_NO_SYSTEM_RESOURCES

  Se superó el número de sesiones de seguimiento que pueden habilitar el proveedor.

• ERROR_ACCESS_DENIED

  Solo los usuarios con privilegios administrativos, los usuarios del Performance Log Users grupo y los servicios que se ejecutan como LocalSystem, LocalServiceo NetworkService pueden habilitar proveedores de eventos en una sesión entre procesos. Para conceder a un usuario restringido la capacidad de habilitar un proveedor de eventos, agréguelos al Performance Log Users grupo o consulte EventAccessControl.

  Windows XP y Windows 2000: Cualquier persona puede habilitar un proveedor de eventos.

Comentarios

Los controladores de seguimiento de eventos llaman a esta función para configurar los proveedores de eventos que escriben eventos en la sesión. Por ejemplo, un controlador podría llamar a esta función para empezar a recopilar eventos de un proveedor, para ajustar el nivel o las palabras clave de los eventos que se recopilan de un proveedor o para detener la recopilación de eventos de un proveedor.

Esta función está obsoleta. Para obtener funcionalidad adicional, el nuevo código debe usar EnableTraceEx2.

Las dos llamadas de función siguientes son equivalentes:

// Obsolete:
Status = EnableTrace(
    Enable,
    EnableFlag,
    EnableLevel,
    ControlGuid,
    TraceHandle);

// Updated equivalent code:
Status = EnableTraceEx2(
    TraceHandle,
    ControlGuid,
    Enable,      // ControlCode
    EnableLevel,
    EnableFlag,  // MatchAnyKeyword
    0,           // MatchAllKeyword
    0,           // Timeout
    NULL);       // EnableParameters

Para obtener más información sobre la semántica de configuración de proveedores para una sesión, consulte la documentación de EnableTraceEx2.

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	Advapi32.lib
Archivo DLL	Advapi32.dll

Consulte también

StartTrace

EnableTraceEx2