Función EnableTraceEx (evntrace.h)

Artículo
06/12/2024

Un controlador de sesión de seguimiento llama a EnableTraceEx 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 EnableTraceEx(
  [in]           LPCGUID                  ProviderId,
  [in, optional] LPCGUID                  SourceId,
                 CONTROLTRACE_ID          TraceId,
  [in]           ULONG                    IsEnabled,
  [in]           UCHAR                    Level,
  [in]           ULONGLONG                MatchAnyKeyword,
  [in]           ULONGLONG                MatchAllKeyword,
  [in]           ULONG                    EnableProperty,
  [in, optional] PEVENT_FILTER_DESCRIPTOR EnableFilterDesc
);

Parámetros

[in] ProviderId

Identificador de proveedor (GUID de control) del proveedor de eventos que desea configurar.

[in, optional] SourceId

GUID que puede identificar de forma única el origen de esta solicitud de configuración o NULL si no se necesita ninguna identidad de origen (equivalente a establecer SourceId en &GUID_NULL). Si se especifica, este valor se usa como parámetro SourceId al invocar enableCallback del proveedor.

Nota

No siempre hay una asignación directa entre una llamada a EnableTrace y una llamada correspondiente a EnableCallback del proveedor. Por ejemplo, si se llama a EnableTrace para un proveedor que aún no se ha registrado, la llamada a EnableCallback se aplazará hasta que se produzca el registro y, si se detiene una sesión de consumidor de seguimiento, ETW invocará EnableCallback aunque no haya ninguna llamada correspondiente a EnableTrace. En tales casos, Se invocará EnableTrace con SourceId establecido en GUID_NULL.

TraceId

[in] IsEnabled

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] Level

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 MatchAnyKeyword y MatchAllKeyword .

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] MatchAnyKeyword

Máscara de bits de 64 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 conjunto de bits de palabra clave, además de cumplir los criterios Level y MatchAllKeyword .

[in] MatchAllKeyword

Máscara de bits de 64 bits de palabras clave que restringe los eventos que desea que escriba el proveedor. Normalmente, el proveedor escribe un evento si los bits de palabra clave del evento coinciden con todos los bits establecidos en este valor o si el evento no tiene ningún bit de palabra clave establecido, además de cumplir los criterios Level y MatchAnyKeyword .

Este valor se establece con frecuencia en 0.

[in] EnableProperty

Marcas que especifican comportamientos especiales que el tiempo de ejecución de ETW debe habilitar al recopilar eventos de este proveedor. Para habilitar comportamientos especiales, especifique una o varias de las marcas siguientes. De lo contrario, establezca EnableProperty en 0.

Nota

Varias de estas marcas indican que ETW debe incluir información adicional en cada evento. Los datos se escriben en la sección de elementos de datos extendidos del evento.

Valor	Significado
EVENT_ENABLE_PROPERTY_SID	Incluya el identificador de seguridad (SID) del usuario en los datos extendidos.
EVENT_ENABLE_PROPERTY_TS_ID	Incluya el identificador de sesión de terminal en los datos extendidos.
EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0	La sesión de seguimiento no debe registrar eventos que tengan una palabra clave 0.

[in, optional] EnableFilterDesc

Estructura EVENT_FILTER_DESCRIPTOR que apunta a los datos de filtro. El proveedor lo usa para filtrar los datos para evitar que los eventos que no coincidan con los criterios de filtro se escriban en la sesión. El proveedor determina el diseño de los datos y cómo aplica el filtro a los datos del evento. Una sesión solo puede pasar un filtro al proveedor.

Una sesión puede llamar a la función TdhEnumerateProviderFilters para buscar los filtros para los que un proveedor ha registrado compatibilidad.

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:
- ProviderId es NULL.
- TraceHandle es NULL.
ERROR_INVALID_FUNCTION

No se puede actualizar el nivel cuando el proveedor no está registrado.
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.

En la mayoría de los casos, una llamada a EnableTraceEx se puede convertir a EnableTraceEx2 de la siguiente manera:

// Obsolete:
Status =
EnableTraceEx(
    ProviderId,
    NULL,           // SourceId
    TraceHandle,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    0,              // EnableProperty
    NULL);          // EnableFilterDesc

// Updated equivalent code:
Status = EnableTraceEx2(
    TraceHandle,
    ProviderId,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    0,              // Timeout
    NULL);          // EnableParameters

En escenarios más complejos, se puede convertir una llamada a EnableTraceEx a EnableTraceEx2 de la siguiente manera:

// Obsolete:
Status =
EnableTraceEx(
    ProviderId,
    SourceId,
    TraceHandle,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    EnableProperty,
    EnableFilterDesc);

// Updated equivalent code:
ENABLE_TRACE_PARAMETERS EnableParameters = {
    ENABLE_TRACE_PARAMETERS_VERSION_2,
    EnableProperty,
    0,                 // ControlFlags
    SourceId ? *SourceId : GUID_NULL,
    EnableFilterDesc,
    EnableFilterDesc ? 1 : 0 };
Status = EnableTraceEx2(
    TraceHandle,
    ProviderId,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    0,                 // Timeout
    &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

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

Consulte también

StartTrace

EnableTraceEx2

Compartir a través de

Función EnableTraceEx (evntrace.h)

Sintaxis

Parámetros

Valor devuelto

Comentarios

Requisitos

Consulte también

Comentarios

Recursos adicionales