ControlTraceA 함수(evntrace.h)
ControlTrace 함수는 지정된 이벤트 추적 세션을 플러시, 쿼리, 업데이트 또는 중지합니다.
구문
ULONG WMIAPI ControlTraceA(
CONTROLTRACE_ID TraceId,
[in] LPCSTR InstanceName,
[in, out] PEVENT_TRACE_PROPERTIES Properties,
[in] ULONG ControlCode
);
매개 변수
TraceId
[in] InstanceName
이벤트 추적 세션 또는 NULL의 이름입니다. TraceHandle이 0인 경우 InstanceName을 지정해야 합니다.
NT 커널 로거 세션을 지정하려면 InstanceName 을 KERNEL_LOGGER_NAME 설정합니다.
[in, out] Properties
초기화된 EVENT_TRACE_PROPERTIES 구조체에 대한 포인터입니다. 필드를 설정하기 전에 이 구조체를 0으로 설정해야 합니다.
ControlCode가 EVENT_TRACE_CONTROL_STOP, EVENT_TRACE_CONTROL_QUERY 또는 EVENT_TRACE_CONTROL_FLUSH 지정하는 경우 EVENT_TRACE_PROPERTIES 구조체의 Wnode.BufferSize, Wnode.Guid, LoggerNameOffset 및 LogFileNameOffset 멤버만 설정하면 됩니다. 세션이 프라이빗 세션인 경우 LogFileMode도 설정해야 합니다. 최대 세션 이름(1024자) 및 최대 로그 파일 이름(1024자) 길이를 사용하여 버퍼 크기와 오프셋을 계산할 수 있습니다(알 수 없는 경우).
ControlCode가 EVENT_TRACE_CONTROL_UPDATE 지정하는 경우 입력에서 멤버는 업데이트할 속성에 대한 새 값을 지정해야 합니다. 출력에서 속성 에는 이벤트 추적 세션에 대한 속성과 통계가 포함됩니다. 다음 속성을 업데이트할 수 있습니다.
EnableFlags: 모든 시스템 공급자를 사용하지 않도록 설정하려면 이 멤버를 0으로 설정합니다. 이 값을 0이 아닌 값으로 설정하여 사용하도록 설정하거나 계속 사용하도록 설정할 시스템 공급자를 지정합니다. 시스템 로거에 대해서만 0이 아닐 수 있습니다.
FlushTimer: 버퍼를 플러시하기 전에 대기할 시간을 변경하려면 이 멤버를 설정합니다. 이 멤버가 0이면 멤버가 업데이트되지 않습니다.
LogFileNameOffset: 다른 로그 파일로 전환하거나 버퍼링 모드 추적을 새 로그 파일로 플러시하려면 이 멤버를 설정합니다. 이 멤버가 0이면 파일 이름이 업데이트되지 않습니다. 오프셋이 0이 아니고 로그 파일 이름을 변경하지 않으면 함수는 오류를 반환합니다.
LogFileMode: EVENT_TRACE_REAL_TIME_MODE 켜고 끄려면 이 멤버를 설정합니다. 실시간 소모를 끄려면 이 멤버를 0으로 설정합니다. 실시간 소비를 켜려면(디스크에 기록되는 세션을 만들고 실시간으로 이벤트를 배달) 이 멤버를 EVENT_TRACE_REAL_TIME_MODE 설정하면 현재 모드에서 OR가 됩니다.
MaximumBuffers: ETW에서 사용하는 최대 버퍼 수를 변경하려면 이 멤버를 설정합니다. 이 멤버가 0이면 멤버가 업데이트되지 않습니다.
프라이빗 로거 세션의 경우 LogFileNameOffset 및 FlushTimer 멤버만 업데이트할 수 있습니다.
새로 초기화된 EVENT_TRACE_PROPERTIES 구조를 사용하는 경우 구조체를 제로 아웃한 다음 Wnode.BufferSize, Wnode.Guid 및 Wnode.Flags 및 업데이트하려는 값을 설정합니다.
EVENT_TRACE_PROPERTIES 구조를 다시 사용하는 경우(즉, 이전에 StartTrace 또는 ControlTrace에 전달한 구조체 사용) 로그 파일 이름을 변경하지 않는 한 LogFileNameOffset 멤버를 0으로 설정하고 EVENT_TRACE_PROPERTIES 설정해야 합니다. Wnode.Flags를 WNODE_FLAG_TRACED_GUID.
Windows 10 버전 1703부터: 프로세스 간 시나리오에서 성능을 향상시키려면 이제 시스템 전체 프라이빗 로거에 대한 ControlTrace 에 필터링 정보를 전달할 수 있습니다. 필터링 정보를 포함하려면 EVENT_TRACE_PROPERTIES_V2 구조를 사용해야 합니다. 자세한 내용은 프라이빗 로거 세션 구성 및 시작을 참조하세요.
[in] ControlCode
요청된 컨트롤 함수입니다. 다음 값 중 하나를 지정할 수 있습니다.
EVENT_TRACE_CONTROL_FLUSH: 세션의 활성 버퍼를 플러시합니다.
메모리 내 세션( EVENT_TRACE_BUFFERING_MODE 플래그로 시작된 세션)과 함께 추적의 데이터를 파일에 쓰는 데 사용할 수 있습니다.
ETW가 가득 찼을 때(즉, 다음 이벤트에 대한 공간이 없는 경우), 추적 세션의 FlushTimer가 만료되는 경우 또는 추적 세션이 닫힌 경우 자동으로 버퍼를 플러시하므로 일반적으로 파일 기반 또는 실시간 세션을 플러시할 필요가 없습니다.
Windows 2000: 이 값은 지원되지 않습니다.
EVENT_TRACE_CONTROL_QUERY: 세션 속성 및 통계를 검색합니다.
EVENT_TRACE_CONTROL_STOP: 세션을 중지합니다. 세션 핸들이 더 이상 유효하지 않습니다.
EVENT_TRACE_CONTROL_UPDATE: 세션 속성을 업데이트합니다.
EVENT_TRACE_CONTROL_INCREMENT_FILE: 세션에 가 있는
EVENT_TRACE_FILE_MODE_NEWFILE경우 이전 파일이 채워지는 것을 기다리지 않고 즉시 다음 파일로 전환하도록 세션을 업데이트합니다. Windows 10 2018년 10월 업데이트부터 지원됩니다.EVENT_TRACE_CONTROL_CONVERT_TO_REALTIME: 파일 모드 세션을 실시간 세션으로 변경합니다(실시간 배달을 사용하도록 설정하고 ETL 파일에 이벤트 쓰기를 사용하지 않도록 설정). Windows 10 2020년 10월 업데이트부터 지원됩니다.
참고
버퍼를 플러시하거나 DllMain에서 추적 세션을 중지하는 것은 안전하지 않습니다(교착 상태를 일으킬 수 있음).
반환 값
함수가 성공하면 반환 값이 ERROR_SUCCESS.
함수가 실패하면 반환 값은 시스템 오류 코드 중 하나입니다. 다음은 몇 가지 일반적인 오류와 그 원인입니다.
ERROR_BAD_LENGTH
다음 중 하나에 해당합니다.
- 속성의 Wnode.BufferSize 멤버는 잘못된 크기를 지정합니다.
- 속성 에는 세션 이름 및 로그 파일 이름(사용된 경우)의 복사본을 보관할 충분한 공간이 할당되지 않았습니다.
ERROR_INVALID_PARAMETER
다음 중 하나에 해당합니다.
- 속성 은 NULL입니다.
- InstanceName 과 TraceHandle 은 모두 NULL입니다.
- InstanceName 은 NULL 이고 TraceHandle 은 유효한 핸들이 아닙니다.
- 속성의 LogFileNameOffset 멤버가 잘못되었습니다.
- 속성의 LoggerNameOffset 멤버가 잘못되었습니다.
- 속성의 LogFileMode 멤버는 유효하지 않은 플래그의 조합을 지정합니다.
- 속성의 Wnode.Guid 멤버는 SystemTraceControlGuid이지만 InstanceName 매개 변수는 가 아닙니다
KERNEL_LOGGER_NAME.
ERROR_BAD_PATHNAME
다른 세션에서는 속성 구조의 LogFileNameOffset 멤버가 지정한 파일 이름을 이미 사용하고 있습니다.
ERROR_MORE_DATA
EVENT_TRACE_PROPERTIES 버퍼가 너무 작아 세션에 대한 모든 정보를 보유할 수 없습니다. 세션의 속성 정보가 필요하지 않은 경우 이 오류를 무시할 수 있습니다. 세션을 중지할 때 이 오류가 발생하면 ETW는 이 오류를 생성하기 전에 세션을 이미 중지했습니다.
ERROR_ACCESS_DENIED
관리자 권한으로 실행되는 사용자, 성능 로그 사용자 그룹의 사용자 및 LocalSystem, LocalService, NetworkService로 실행되는 서비스만 이벤트 추적 세션을 제어할 수 있습니다. 제한된 사용자에게 추적 세션을 제어할 수 있는 기능을 부여하려면 성능 로그 사용자 그룹에 추가합니다. LocalSystem으로 실행되는 관리 권한 및 서비스를 가진 사용자만 NT 커널 로거 세션을 제어할 수 있습니다.
Windows XP 및 Windows 2000: 누구나 추적 세션을 제어할 수 있습니다.
ERROR_WMI_INSTANCE_NOT_FOUND
지정된 세션이 실행되고 있지 않습니다.
설명
이벤트 추적 컨트롤러는 이 함수를 호출합니다.
이 함수는 FlushTrace, QueryTrace, StopTrace 및 UpdateTrace 함수를 대체합니다.
참고
evntrace.h 헤더는 CONTROLTrace를 유니코드 전처리기 상수의 정의에 따라 이 함수의 ANSI 또는 유니코드 버전을 자동으로 선택하는 별칭으로 정의합니다. 인코딩 중립 별칭을 인코딩 중립이 아닌 코드와 혼합하면 컴파일 또는 런타임 오류가 발생하는 불일치가 발생할 수 있습니다. 자세한 내용은 함수 프로토타입에 대한 규칙을 참조하세요.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows 2000 Professional [데스크톱 앱 | UWP 앱] |
| 지원되는 최소 서버 | Windows 2000 Server [데스크톱 앱 | UWP 앱] |
| 대상 플랫폼 | Windows |
| 헤더 | evntrace.h |
| 라이브러리 | Windows 8.1 및 Windows Server 2012 R2의 Sechost.lib; Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista 및 Windows XP의 Advapi32.lib |
| DLL | Windows 8.1 및 Windows Server 2012의 Sechost.dll. Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista 및 Windows XP의 Advapi32.dll |