EventActivityIdControl 함수(evntprov.h)

아티클
08/23/2023

ETW 이벤트에서 사용할 활동 식별자를 만들고, 쿼리하고, 설정합니다.

구문

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

매개 변수

[in] ControlCode

수행할 작업을 지정하는 컨트롤 코드입니다.

EVENT_ACTIVITY_CTRL_GET_ID

ActivityId 매개 변수를 현재 스레드의 작업 ID 값으로 설정합니다.
EVENT_ACTIVITY_CTRL_SET_ID

현재 스레드의 작업 ID를 ActivityId 매개 변수 값으로 설정합니다.
EVENT_ACTIVITY_CTRL_CREATE_ID

ActivityId 매개 변수를 새로 생성된 로컬 고유 활동 ID 값으로 설정합니다.
EVENT_ACTIVITY_CTRL_GET_SET_ID

ActivityId 매개 변수의 값과 현재 스레드의 작업 ID를 교환합니다. (현재 스레드의 활동 ID 값을 저장한 다음 현재 스레드의 활동 ID를 ActivityId 매개 변수 값으로 설정한 다음 ActivityId 매개 변수를 저장된 값으로 설정합니다.)
EVENT_ACTIVITY_CTRL_CREATE_SET_ID

ActivityId 매개 변수를 현재 스레드의 작업 ID 값으로 설정한 다음 현재 스레드의 활동 ID를 새로 생성된 로컬 고유 작업 ID 값으로 설정합니다.

[in, out] ActivityId

128비트 활동 ID를 포함하는 버퍼에 대한 포인터입니다. 이 버퍼는 ControlCode 매개 변수의 값에 따라 읽기 및/또는 기록될 수 있습니다.

반환 값

성공하면 ERROR_SUCCESS 반환합니다.

설명

EventWrite API 중 하나를 사용하여 작성된 ETW 이벤트는 128비트 "활동 ID" 필드를 포함하며 필요에 따라 128비트 "관련 활동 ID" 필드를 포함할 수 있습니다. 추적 처리 도구는 이러한 필드의 값을 사용하여 이벤트를 활동이라는 그룹으로 구성할 수 있습니다.

활동 ID가 0인 모든 이벤트(예: GUID_NULL)는 활동의 일부가 아닌 것으로 간주됩니다.
0이 아닌 특정 활동 ID가 있는 모든 이벤트는 동일한 활동의 일부로 간주됩니다.
활동의 시작을 나타내려면 공급자는 Opcode를 0이 아닌 특정 활동 ID(시작 이벤트)가 있는 첫 번째 이벤트에 대해 WINEVENT_OPCODE_START 설정해야 합니다. 활동이 다른 작업 내에 논리적으로 중첩된 경우 공급자는 시작 이벤트의 관련 활동 ID 필드를 부모 활동의 ID로 설정해야 합니다.
활동의 끝을 나타내려면 공급자는 Opcode를 0이 아닌 특정 활동 ID(중지 이벤트)가 있는 마지막 이벤트에 대해 WINEVENT_OPCODE_STOP 설정해야 합니다.

활동 ID가 유용하려면 새로 생성된 활동 ID가 로컬에서 고유해야 합니다. 즉, 추적 내에서 동일한 ID를 두 번 생성해서는 안 됩니다.

EventActivityIdControl을 사용하여 활동 ID를 만들 수 있습니다. 이 ID는 시스템이 다시 부팅될 때까지 로컬 시스템의 모든 프로세스에서 고유하도록 보장되는 로컬 고유 ID를 생성합니다. GUID(전역 고유 식별자)를 활동 ID로 사용할 수도 있습니다. UuidCreate와 같은 API를 사용하여 GUID를 만들 수 있습니다.

사용자 모드 스레드에는 스레드 로컬 128비트 활동 ID 값(스레드의 활동 ID)이 있습니다. 스레드 활동 ID는 스레드를 만들 때 0(즉 , GUID_NULL)으로 초기화됩니다. EventActivityIdControl을 사용하여 스레드 작업 ID를 읽거나 업데이트할 수 있습니다. 스레드 활동 ID는 EventWrite에서 작성한 모든 이벤트 및 ActivityId 매개 변수가 NULL인 EventWriteTransfer 또는 EventWriteEx에서 작성한 모든 이벤트에 대한 활동 ID로 사용됩니다.

중요

스레드의 작업 ID를 변경하는 함수는 종료하기 전에 원래 활동 ID를 복원하는 데 주의해야 합니다. 그렇지 않으면 스레드의 작업 ID에 대한 함수 변경 내용이 함수를 호출하는 구성 요소의 활동을 방해합니다.

명시적으로 지정된 활동 ID 사용

활동이 단일 스레드로 제한되지 않거나 스레드의 활동 ID를 덮어쓰는 다른 구성 요소의 간섭 가능성을 방지하려는 경우 자동 스레드 작업 ID를 사용하는 대신 EventWriteTransfer 또는 EventWriteEx의 ActivityId 필드를 통해 이벤트 활동을 명시적으로 지정할 수 있습니다.

매니페스트 및 메시지 컴파일러를 사용하여 이벤트를 작성하는 경우 에서 생성된 MC.exe -um 매크로는 스레드의 작업 ID를 사용하고 에서 생성된 MC.exe -km 매크로는 활동 ID 매개 변수를 지원합니다. 원래 매크로는 -um 사용자 모드에서만 작동했고 -km 매크로는 커널 모드에서만 작동했기 때문에 사용자 모드 코드는 현재 스레드의 작업 ID만 사용할 수 있었습니다. 그러나 MC.exe 버전 10.0.17741부터 에서 생성된 MC.exe -km 매크로는 사용자 모드와 커널 모드 모두에 사용할 수 있으므로 를 사용하여 MC.exe -km 활동 ID 매개 변수를 허용하는 매크로를 생성할 수 있습니다. MC에서 생성된 코드는 이벤트의 관련 활동 ID 설정을 지원하지 않습니다.

TraceLoggingProvider.h를 사용하여 이벤트를 작성하는 경우 TraceLoggingWrite 매크로는 스레드의 작업 ID를 사용하는 반면 TraceLoggingWriteActivity는 활동 ID 및 관련 활동 ID에 대한 매개 변수를 허용합니다. 또는 TraceLogging 작업에 TraceLoggingActivity.h 의 C++ 클래스를 사용할 수 있습니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	evntprov.h
라이브러리	Advapi32.lib
DLL	Advapi32.dll

추가 정보

EventWriteTransfer