Función EventActivityIdControl (evntprov.h)

Crea, consulta y establece identificadores de actividad para su uso en eventos ETW.

Sintaxis

ULONG EVNTAPI EventActivityIdControl(
  [in]      ULONG  ControlCode,
  [in, out] LPGUID ActivityId
);

Parámetros

[in] ControlCode

Código de control que especifica la operación que se va a realizar.

• EVENT_ACTIVITY_CTRL_GET_ID

  Establece el parámetro ActivityId en el valor del identificador de actividad del subproceso actual.

• EVENT_ACTIVITY_CTRL_SET_ID

  Establece el identificador de actividad del subproceso actual en el valor del parámetro ActivityId .

• EVENT_ACTIVITY_CTRL_CREATE_ID

  Establece el parámetro ActivityId en el valor de un identificador de actividad único local recién generado.

• EVENT_ACTIVITY_CTRL_GET_SET_ID

  Intercambia los valores del parámetro ActivityId y el identificador de actividad del subproceso actual. (Guarda el valor del identificador de actividad del subproceso actual y, a continuación, establece el identificador de actividad del subproceso actual en el valor del parámetro ActivityId y, a continuación, establece el parámetro ActivityId en el valor guardado).

• EVENT_ACTIVITY_CTRL_CREATE_SET_ID

  Establece el parámetro ActivityId en el valor del identificador de actividad del subproceso actual y, a continuación, establece el identificador de actividad del subproceso actual en el valor de un identificador de actividad único localmente recién generado.

[in, out] ActivityId

Puntero a un búfer que contiene un identificador de actividad de 128 bits. Este búfer puede leerse o escribirse en , según el valor del parámetro ControlCode .

Valor devuelto

Devuelve ERROR_SUCCESS si se ejecuta correctamente.

Comentarios

Los eventos ETW escritos mediante una de las API de EventWrite contendrán un campo de "id. de actividad" de 128 bits y, opcionalmente, pueden contener un campo "id. de actividad relacionado" de 128 bits. Las herramientas de procesamiento de seguimiento pueden usar los valores de estos campos para organizar eventos en grupos denominados actividades.

• Se supone que todos los eventos con un identificador de actividad de cero (es decir , GUID_NULL) no forman parte de ninguna actividad.
• Se supone que todos los eventos que tienen un identificador de actividad distinto de cero determinado forman parte de la misma actividad.
• Para indicar el principio de la actividad, el proveedor debe establecer Opcode en WINEVENT_OPCODE_START para el primer evento con un identificador de actividad distinto de cero determinado (el evento de inicio ). Si la actividad está anidada lógicamente dentro de otra actividad, el proveedor debe establecer el campo id. de actividad relacionada del evento de inicio en el identificador de la actividad primaria.
• Para indicar el final de la actividad, el proveedor debe establecer Opcode en WINEVENT_OPCODE_STOP para el último evento con un identificador de actividad distinto de cero determinado (el evento stop ).

Para que los identificadores de actividad sean útiles, los identificadores de actividad recién generados deben ser únicos localmente, es decir, el mismo identificador no se debe generar dos veces dentro del seguimiento.

Puede crear identificadores de actividad mediante EventActivityIdControl, que genera identificadores únicos localmente que se garantiza que sean únicos en todos los procesos del sistema local hasta que se reinicie el sistema. También puede usar un GUID (identificador único global) como identificador de actividad. Puede crear un GUID mediante una API como UuidCreate.

Los subprocesos en modo de usuario tienen un valor de identificador de actividad local de 128 bits (identificador de actividad del subproceso). El identificador de actividad del subproceso se inicializa en 0 (es decir , GUID_NULL) cuando se crea el subproceso. El identificador de actividad del subproceso se puede leer o actualizar mediante EventActivityIdControl. El identificador de actividad del subproceso se usará como identificador de actividad para todos los eventos escritos por EventWrite y para todos los eventos escritos por EventWriteTransfer o EventWriteEx donde el parámetro ActivityId es NULL.

Importante

Una función que modifique el identificador de actividad de un subproceso debe tener cuidado de restaurar el identificador de actividad original antes de salir. De lo contrario, los cambios de la función en el identificador de actividad del subproceso interferirán con las actividades de los componentes que llaman a la función.

Uso de un identificador de actividad especificado explícitamente

En los casos en los que las actividades no se limitan a un único subproceso o en los que desea evitar la posibilidad de interferencia de otros componentes sobrescribir el identificador de actividad del subproceso, es posible que desee especificar explícitamente actividades de evento a través del campo ActivityId de EventWriteTransfer o EventWriteEx en lugar de usar el identificador de actividad de subproceso automático.

Si usa manifiestos y compilador de mensajes para escribir eventos, las macros generadas por MC.exe -um usan el identificador de actividad del subproceso mientras las macros generadas por MC.exe -km admiten un parámetro de identificador de actividad. Originalmente, las -um macros solo funcionaban en modo de usuario y las -km macros solo funcionaban en modo kernel, por lo que el código en modo de usuario solo podía usar el identificador de actividad del subproceso actual. Sin embargo, a partir de MC.exe versión 10.0.17741, las macros generadas por MC.exe -km se pueden usar para el modo de usuario y el modo kernel, por lo que puede usar MC.exe -km para generar macros que aceptan un parámetro de identificador de actividad. (El código generado por MC no admite la configuración del identificador de actividad relacionado de un evento).

Si usa TraceLoggingProvider.h para escribir eventos, la macro TraceLoggingWrite usa el identificador de actividad del subproceso, mientras que TraceLoggingWriteActivity acepta parámetros para el identificador de actividad y el identificador de actividad relacionado. Como alternativa, puede usar las clases de C++ en TraceLoggingActivity.h para las actividades de TraceLogging.

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

Consulte también

EventWriteTransfer