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 |