StartTraceA 함수(evntrace.h)

아티클
03/11/2023

StartTrace 함수는 이벤트 추적 세션을 등록하고 시작합니다.

중요

교차 프로세스 이벤트 추적 세션은 제한된 시스템 리소스입니다. 개발자는 고객 머신에서 이벤트 추적 세션을 시작하지 않아야 합니다. 이벤트 추적 세션이 필요한 경우 가능한 가장 작은 범위로 제한되어야 합니다. 가능한 한 적은 수의 세션을 사용하고, 가능한 경우 In-Process 전용 세션을 사용하고(EVENT_TRACE_PRIVATE_LOGGER_MODE | EVENT_TRACE_PRIVATE_IN_PROC) 시나리오에 컬렉션이 특별히 필요한 경우에만 추적을 시작하고, 시나리오가 완료되는 즉시 추적을 중지하고, 세션에서 사용되는 메모리 양을 제한합니다. 불필요한 이벤트를 수집하지 않도록 엄격한 이벤트 필터를 사용합니다.

구문

ULONG WMIAPI StartTraceA(
  [out]     PTRACEHANDLE            TraceHandle,
  [in]      LPCSTR                  InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties
);

매개 변수

[out] TraceHandle

ControlTrace와 같은 API에서 후속 사용을 위해 이벤트 추적 세션에 대한 핸들을 받습니다.

함수가 실패하는 경우 이 핸들을 사용하지 마세요. 세션 핸들을 INVALID_HANDLE_VALUE 비교하지 마세요. 핸들이 유효하지 않은 경우 세션 핸들은 0입니다.

[in] InstanceName

이벤트 추적 세션의 이름을 포함하는 Null로 종료된 문자열입니다. 세션 이름은 1,024자로 제한되며 대/소문자를 구분하지 않으며 고유해야 합니다.

중요

세션 이름에서 세션의 소유권 및 사용량을 확인할 수 있도록 세션에 대한 설명이 포함된 이름을 사용합니다. GUID 또는 기타 비결정적 또는 설명이 없는 값을 사용하지 마세요. 세션 이름을 고유하게 만들려면 임의의 숫자를 추가하지 마세요. ETW 세션은 제한된 리소스이므로 구성 요소가 여러 세션을 시작하지 않아야 합니다. 구성 요소가 시작될 때 구성 요소의 세션이 이미 실행 중인 경우 구성 요소는 두 번째 세션을 만드는 대신 분리된 세션을 정리해야 합니다.

이 함수는 속성의 LoggerNameOffset 멤버가 가리키는 오프셋에 제공하는 세션 이름을 복사합니다.

[in, out] Properties

세션의 동작을 지정하는 EVENT_TRACE_PROPERTIES 구조체에 대한 포인터입니다. 다음은 설정할 구조체의 주요 멤버입니다.

Wnode.BufferSize
Wnode.Guid
Wnode.ClientContext
Wnode.Flags
LogFileMode
LogFileNameOffset
LoggerNameOffset

만들려는 로그 파일의 형식에 따라 MaximumFileSize 값을 지정해야 할 수도 있습니다. Properties 매개 변수 설정 및 세션 동작에 대한 자세한 내용은 설명 섹션을 참조하세요.

Windows 10 버전 1703부터: 프로세스 간 시나리오에서 성능을 향상시키려면 이제 시스템 전체 프라이빗 로거를 시작할 때 StartTrace에 필터링을 전달할 수 있습니다. 필터링 정보를 포함하려면 새 EVENT_TRACE_PROPERTIES_V2 구조를 전달해야 합니다. 자세한 내용은 프라이빗 로거 세션 구성 및 시작을 참조하세요.

반환 값

함수가 성공하면 반환 값이 ERROR_SUCCESS.

함수가 실패하면 반환 값은 시스템 오류 코드 중 하나입니다. 다음은 몇 가지 일반적인 오류와 그 원인입니다.

ERROR_BAD_LENGTH

다음 중 하나에 해당합니다.
- 속성의 Wnode.BufferSize 멤버는 잘못된 크기를 지정합니다.
- 속성 에 InstanceName 복사본을 보관할 충분한 공간이 할당되지 않았습니다.
ERROR_INVALID_PARAMETER

다음 중 하나에 해당합니다.
- 속성 은 NULL입니다.
- TraceHandle 은 NULL입니다.
- 속성의 LogFileNameOffset 멤버가 잘못되었습니다.
- 속성의 LoggerNameOffset 멤버가 잘못되었습니다.
- 속성의 LogFileMode 멤버는 유효하지 않은 플래그의 조합을 지정합니다.
- Wnode.Guid 멤버는 SystemTraceControlGuid이지만 InstanceName 매개 변수는 KERNEL_LOGGER_NAME 않습니다.
ERROR_ALREADY_EXISTS

이름이 같거나 GUID가 같은 세션이 이미 실행 중입니다.
ERROR_BAD_PATHNAME

다음 이유 중 하나로 이 오류가 발생할 수 있습니다.
- 다른 세션에서는 속성 구조의 LogFileNameOffset 멤버가 지정한 파일 이름을 이미 사용하고 있습니다.
- LogFileMode와 LogFileNameOffset은 모두 0입니다.
ERROR_DISK_FULL

드라이브에 로그 파일의 여유 공간이 충분하지 않습니다. 이 문제는 다음과 같은 경우에 발생합니다.
- MaximumFileSize 가 0이 아니고 로그 파일에 사용할 수 있는 MaximumFileSize 바이트가 없습니다.
- 드라이브는 시스템 드라이브이며 200MB를 추가로 사용할 수 없습니다.
- MaximumFileSize 가 0이고 200MB를 추가로 사용할 수 없습니다.
공간이 더 많은 드라이브를 선택하거나 MaximumFileSize 에 지정된 크기를 줄입니다(사용된 경우).
ERROR_ACCESS_DENIED

관리자 권한이 있는 사용자, 성능 로그 사용자 그룹의 사용자 및 LocalSystem, LocalService, NetworkService로 실행되는 서비스만 이벤트 추적 세션을 제어할 수 있습니다. 제한된 사용자에게 추적 세션을 제어할 수 있는 기능을 부여하려면 성능 로그 사용자 그룹에 추가합니다. LocalSystem으로 실행되는 관리 권한 및 서비스를 가진 사용자만 NT 커널 로거 세션을 제어할 수 있습니다.

사용자가 성능 로그 사용자 그룹의 구성원인 경우 지정된 폴더에 로그 파일을 만들 수 있는 권한이 없을 수 있습니다.
ERROR_NO_SYSTEM_RESOURCES

다음 중 하나에 해당합니다.
- 로깅 세션은 EVENT_TRACE_SYSTEM_LOGGER_MODE 플래그를 사용하며 최대 시스템 로거 수(8)에 도달했습니다.
- 시스템의 최대 로깅 세션 수에 도달했습니다. 로깅 세션이 중지될 때까지 새 로거를 만들 수 없습니다. 대부분의 시스템에서 최대 로깅 세션 수는 64개입니다.
  
  에서 HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\WMI@EtwMaxLoggersREG_DWORD 키를 편집하여 시스템의 최대 로깅 세션 수를 변경할 수 있습니다. 허용되는 값은 32~256이며 포함됩니다. 변경 내용을 적용하려면 다시 부팅해야 합니다.
  
  로거는 시스템 리소스를 사용합니다. 시스템의 로거 수를 늘리면 해당 슬롯이 채워지면 성능 비용이 듭니다. 이 제한은 시스템 리소스의 과도한 사용을 방지하기 위해 존재합니다.
  
  중요
  
  제한은 특정 시나리오를 사용하도록 시스템 관리자만 수동으로 조정해야 합니다. EtwMaxLoggers 설정은 프로그램 또는 드라이버에서 자동으로 수정해서는 안 됩니다.
  
  Windows 10 버전 1709 이전에는 비공개 로거가 아닌 로거에 대해 64로거의 고정 상한입니다.

설명

이벤트 추적 컨트롤러는 이 함수를 호출합니다.

세션이 중지되거나, 컴퓨터가 다시 시작되거나, I/O 오류가 발생하거나, 순환이 아닌 로그의 최대 파일 크기에 도달할 때까지 세션이 활성 상태로 유지됩니다. 이벤트 추적 세션을 중지하려면 ControlTrace 함수를 호출하고 ControlCode 매개 변수를 EVENT_TRACE_CONTROL_STOP 설정합니다.

동일한 세션 GUID를 사용하여 둘 이상의 세션을 시작할 수 없습니다(에 지정된 Properties.Wnode.Guid대로). 대부분의 경우 ETW 시스템이 세션에 대한 새 GUID를 생성할 수 있도록 0(예: GUID_NULL)으로 설정합니다Properties.Wnode.Guid.

프라이빗 로거 세션을 지정하려면 속성의 Wnode.Guid 멤버를 프라이빗 로거 세션의 컨트롤 GUID가 아닌 공급자의 컨트롤 GUID로 설정합니다. StartTrace를 호출하기 전에 공급자가 GUID를 등록해야 합니다.

이 함수를 사용하여 전역 로거 세션을 시작하지 않습니다(사용되지 않음). 전역 로거 세션 시작에 대한 자세한 내용은 전역 로거 세션 구성 및 시작을 참조하세요.

시스템 로거

로거가 시스템 로거이고 SystemTraceProvider 또는 다른 시스템 공급자로부터 이벤트를 수신하려면 다음 중 어느 것이라도 true여야 합니다.

속성 멤버 LogFileMode에는 EVENT_TRACE_SYSTEM_LOGGER_MODE 플래그(기본 설정)가 포함됩니다.
Properties 멤버 Wnode.Guid는 SystemTraceControlGuid 또는 GlobalLoggerGuid로 설정됩니다(사용되지 않음 - 이러한 GUID를 사용하려고 하는 다른 구성 요소와 충돌하기 때문에 새 코드에는 사용되지 않음).
InstanceName 은 KERNEL_LOGGER_NAME 설정됩니다(이 이름을 사용하려고 하는 다른 구성 요소와 충돌하기 때문에 새 코드에는 사용되지 않음).

참고

시스템 로거는 추적에 포함해야 하는 SystemTraceProvider 이벤트를 나타내기 위해 EVENT_TRACE_PROPERTIES 구조체의 EnableFlags 멤버를 설정해야 합니다.

시스템 로거는 특수 커널 이벤트를 받기 때문에 추가 제한 사항이 적용됩니다.

동일한 시스템에서 활성 상태인 시스템 로거는 8개 이하일 수 있습니다.
시스템 로거는 Windows Server 컨테이너 내에서 만들 수 없습니다.
시스템 로거는 EVENT_TRACE_USE_PAGED_MEMORY 플래그를 사용할 수 없습니다.
Windows 10 버전 1703 이전에는 시스템 로거에서 2개 이하의 고유한 클록 형식을 동시에 사용할 수 없습니다. 예를 들어 한 활성 시스템 로거가 "CPU 주기 카운터" 클록 형식을 사용하고 다른 활성 시스템 로거가 "쿼리 성능 카운터" 클록 형식을 사용하는 경우 세 번째 클록 형식의 활성화가 필요하기 때문에 "시스템 시간" 클록 유형을 사용하여 시스템 로거를 시작하려는 시도가 실패합니다. 이러한 제한으로 인해 시스템 로거는 "시스템 시간" 클록 형식을 사용하지 않는 것이 좋습니다.
Windows 10 버전 1703부터 클록 형식 제한이 제거되었습니다. 이제 시스템 로거에서 세 가지 클록 형식을 모두 동시에 사용할 수 있습니다.

NT 커널 로거 세션(사용되지 않음)을 지정하려면 InstanceName을 KERNEL_LOGGER_NAME 설정하고 Properties의 Wnode.Guid 멤버를 SystemTraceControlGuid로 설정합니다. GUID를 SystemTraceControlGuid로 지정하지 않으면 ETW는 GUID 값을 재정의하고 SystemTraceControlGuid로 설정합니다.

예제

StartTrace를 사용하는 예제는 이벤트 추적 세션 구성 및 시작을 참조하세요.

참고

evntrace.h 헤더는 UNICODE 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 StartTrace를 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.

요구 사항


지원되는 최소 클라이언트	Windows Vista [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	evntrace.h
라이브러리	Windows 8.1 및 Windows Server 2012 R2의 Sechost.lib; Advapi32.lib on Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista
DLL	Windows 8.1 및 Windows Server 2012 R2의 Sechost.dll, Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista에서 Advapi32.dll

추가 정보

ControlTrace

EVENT_TRACE_PROPERTIES