StartKernelTrace
이 함수는 커널 이벤트 추적 세션을 등록하고 시작합니다. 이 함수를 사용하여 특정 커널 이벤트에 대해 스택 워킹을 사용하도록 설정할 수도 있습니다.
ULONG
WINAPI
StartKernelTrace(
__out PTRACEHANDLE TraceHandle,
__inout PEVENT_TRACE_PROPERTIES Properties,
__in ULONG cStackTracingEventIds
);
매개 변수
TraceHandle [out]
이벤트 추적 세션에 핸들을 저장합니다. 핸들이 잘못되면 이 매개 변수가 0으로 설정됩니다. 이 매개 변수는 INVALID_HANDLE_VALUE와 비교하면 안 됩니다. 함수가 실패하는 경우 이 핸들을 사용하지 마세요.
Properties [in, out]
EVENT_TRACE_PROPERTIES 구조에 포인터를 저장합니다. EVENT_TRACE_PROPERTIES는 세션 동작의 특정 측면을 구성합니다.
EVENT_TRACE_PROPERTIES 구조의 첫 번째 멤버는 WNODE_HEADER 구조이며 여기에서는 Wnode라고 합니다.
커널 추적 제어를 구성하려면 다음 EVENT_TRACE_PROPERTIES.Wnode 멤버를 설정해야 합니다.
BufferSize
이 멤버는 이벤트 추적 세션 속성에 할당된 메모리의 총 크기(바이트)를 포함합니다. 메모리 크기에는 다음 데이터를 저장할 수 있는 충분한 공간이 포함되어야 합니다.
EVENT_TRACE_PROPERTIES 구조.
세션 이름 문자열.
로그 파일 이름 문자열.
Guid
각 추적 세션에는 세션을 참조하도록 정의된 GUID가 있어야 합니다.
NT 커널 로거 세션의 경우 이 멤버를 SystemTraceControlGuid로 설정해야 합니다. 로깅 모드 상수에 대한 자세한 내용은 NT 커널 로거 상수를 참조하세요.
ClientContext
이 멤버는 각 이벤트에 대한 로깅 타임스탬프를 계산할 때 사용되는 시계 해상도를 설정합니다. 이 멤버의 기본값은 쿼리 성능 카운터입니다.
다음 값 중 하나를 지정할 수 있습니다.
1: QPC(쿼리 성능 카운터). QPC는 고해상도(100나노초) 타임스탬프를 제공하지만 검색하는 데 비교적 비용이 많이 듭니다. 이벤트 속도가 높거나 소비자가 다른 버퍼의 이벤트를 병합하는 경우 이 해상도를 사용합니다. 이전 컴퓨터에서는 하드웨어 오류로 인해 카운터가 앞으로 건너뛰는 경우가 있으므로 타임스탬프가 정확하지 않을 수 있습니다.
2: 시스템 시간. 시스템 시간은 저해상도(10밀리초) 타임스탬프를 제공하지만 검색 비용이 비교적 저렴합니다. 이벤트 볼륨이 높은 경우 시스템 시간 해상도가 이벤트 시퀀스를 결정하기에 충분하지 않을 수 있습니다. 이 경우 이벤트 집합에 동일한 타임스탬프가 있지만 ETW에서 이벤트를 전달하는 순서가 올바르지 않을 수 있습니다.
3: CPU 주기 카운터. CPU 카운터는 가장 높은 해상도의 타임스탬프를 제공하며 검색 비용이 가장 저렴합니다. 그러나 CPU 카운터는 신뢰할 수 없으며 프로덕션에서 사용해서는 안 됩니다. 예를 들어 일부 컴퓨터에서 타이머는 몇 가지 상태에서 정지하는 것 외에도 열 및 전력 변화로 인해 빈도를 변경합니다. 하드웨어에서 이 시계 형식을 지원하지 않는 경우 ETW는 시스템 시간을 사용합니다. Windows Server 2003, Windows XP SP1, Windows XP에서는 이 값이 지원되지 않습니다. Windows Server 2003 SP1 및 Windows XP SP2에 도입되었습니다.
Flags
이 멤버는 구조에 이벤트 추적 정보가 포함되어 있고 정보가 로거로 전송됨을 나타내기 위해 WNODE_FLAG_TRACED_GUID를 포함해야 합니다. WNODE_FLAG_TRACED_GUID는 Evntrace.h에 정의되어 있습니다.
다음 EVENT_TRACE_PROPERTIES 멤버도 설정해야 합니다.
LogFileMode
커널 이벤트 추적 세션에서 사용할 로깅 모드를 나타냅니다. 이 멤버를 사용하여 이벤트가 로그 파일, 실시간 소비자 또는 둘 다에 기록되도록 지정할 수 있습니다.
이 멤버를 사용하여 세션이 프라이빗 로거 세션임을 지정할 수도 있습니다. 하나 이상의 모드를 지정할 수 있습니다. 가능한 모드 목록은 로깅 모드 상수를 참조하세요.
참고 이벤트를 사용할 준비가 된 실시간 소비자가 없는 한 실시간 로깅을 지정하지 마세요. 실시간 소비자가 없는 경우 이벤트는 재생 파일에 기록됩니다. 재생 파일의 크기는 제한됩니다. 제한에 도달하면 로그 파일 또는 재생 파일에 새 이벤트가 기록되지 않습니다. 로깅 기능은 STATUS_LOG_FILE_FULL과 함께 실패합니다.
EnableFlags
이 멤버는 NT 커널 로거 세션에만 사용됩니다. 추적할 이벤트를 커널 로거로 식별합니다. 논리 OR을 사용하면 이 멤버에 하나 이상의 값이 포함될 수 있습니다. 커널 로거는 지정된 이벤트 외에도 하드웨어 구성 이벤트를 기록합니다.
EVENT_TRACE_PROPERTIES에서 제공하는 것 외에도 다음 추적 제어 플래그를 사용할 수 있습니다.
LogFileNameOffset
이 숫자는 구조에 할당된 메모리의 시작부터 로그 파일 이름을 포함하는 null로 끝나는 문자열의 시작까지의 오프셋을 나타냅니다.
고려 사항은 다음과 같습니다.
파일 이름 확장명은 .etl이어야 합니다.
경로의 모든 폴더가 있어야 합니다.
경로는 상대 경로, 절대 경로, 로컬 또는 원격일 수 있습니다.
환경 변수는 확장되지 않으므로 경로는 환경 변수를 포함하지 않아야 합니다.
추적을 시작하는 사용자는 폴더에 대한 쓰기 권한이 있어야 합니다.
로그 파일 이름은 1024자로 제한됩니다.
LogFileMode를 EVENT_TRACE_PRIVATE_LOGGER_MODE 또는 EVENT_TRACE_FILE_MODE_NEWFILE로 설정하는 경우 프라이빗 로거 세션의 파일 이름에 추가되는 프로세스 식별자와 새 파일 로그 모드를 사용하여 만든 로그 파일에 추가되는 순차적 번호를 포함하기에 충분한 메모리를 할당해야 합니다.
이벤트를 로그 파일에 기록하지 않으려면(예: EVENT_TRACE_REAL_TIME_MODE만 지정) LogFileNameOffset을 0으로 설정합니다. 실시간 로깅만 지정하고 유효한 로그 파일 이름과 함께 오프셋을 제공하는 경우 로그 파일 이름을 사용하여 순차 로그 파일을 만들고 이벤트를 로그 파일에 기록합니다. LogFileMode가 0이고 유효한 로그 파일 이름으로 오프셋을 제공하는 경우에도 순차 로그 파일이 만들어집니다.
로그 파일에 이벤트를 기록하려면 구조 다음에 로그 파일 이름과 세션 이름을 포함할 수 있도록 이 구조에 충분한 메모리를 할당해야 합니다. 로그 파일 이름은 메모리의 세션 이름을 따라야 합니다.
추적 파일은 기본 보안 설명자를 사용하여 만들어집니다. 즉, 로그 파일에는 부모 디렉터리와 동일한 ACL이 있어야 합니다. 파일에 대한 액세스를 제한하려면 적절한 ACL을 사용하여 부모 디렉터리를 만듭니다.
LoggerNameOffset
이 멤버는 구조에 할당된 메모리의 시작부터 세션 이름을 포함하는 null로 끝나는 문자열의 시작까지의 오프셋을 나타냅니다.
고려 사항은 다음과 같습니다.
세션 이름은 1024자로 제한됩니다.
세션 이름은 대/소문자를 구분하지 않으며 고유해야 합니다.
이 구조에 메모리를 할당할 때 구조 뒤에 오는 세션 이름과 로그 파일 이름을 포함할 수 있도록 충분한 메모리를 남겨두어야 합니다.
세션 이름은 메모리의 로그 파일 이름 앞에 와야 합니다. 로그 파일 이름은 오프셋 영역에 복사해야 합니다. 이 함수는 KERNEL_LOGGER_NAME에 의해 정의된 세션 이름을 씁니다.
선택한 로그 파일의 형식에 따라 MaximumFileSize 멤버를 설정해야 할 수 있습니다.
참고 이 함수는 항상 KERNEL_LOGGER_NAME 값을 사용하여 StartKernelTrace를 호출하므로 LoggerNameOffset에서 로거 이름을 설정할 필요가 없습니다. 이 함수는 Wnode.Guid가 SystemTraceControlGuid에 해당하는지 확인합니다. 그렇지 않으면 ERROR_INVALID_PARAMETER를 반환합니다. Wnode.Guid가 KernelRundownGuid에 해당하는 경우 로거 이름을 지정해야 합니다. KernelRundownGuid는 기존 프로세스 정보, 스레드 정보, 프로세스당 로드된 이미지, CPU, 비디오, 디스크, 네트워크 카드, 서비스, 전원, 플러그 앤 플레이, 디스크 IDE 채널과 같은 이벤트를 기록하는 데 사용되는 컨트롤 GUID입니다.
반환 값
ERROR_SUCCESS는 성공을 나타냅니다.
가능한 오류 값은 다음 테이블에 설명되어 있습니다.
| 오류 값 | 설명 |
|---|---|
ERROR_ALREADY_EXISTS |
커널 로거의 단일 인스턴스만 시스템에서 실행됩니다. 다른 구성 요소가 커널 로깅을 시작한 후 이 함수가 시작하려고 하면 이 오류가 반환될 수 있습니다. |
ERROR_INVALID_FLAGS |
Properties.EnableFlags에 잘못된 추적 플래그가 있음을 나타낼 수 있습니다. |
ERROR_OUT_OF_MEMORY |
EVENT_TRACE_PROPERTIES에 대한 메모리를 할당하지 못했음을 나타냅니다. |
나열된 것 이외의 이유로 함수가 실패하면 시스템 오류 코드가 반환됩니다.
설명
StackTracingEventIds에 EVENT_TRACE_PROPERTIES.EnableFlags 필드에서 사용하도록 설정하지 않았거나 커널 추적 제어에서 디코딩할 수 없는 이벤트가 포함된 경우 해당 플래그가 무시되고 오류 코드가 반환되지 않습니다.
요구 사항:
버전: Windows Vista부터 사용할 수 있습니다. 이 구조는 Windows Performance Analyzer를 사용하여 배포됩니다.
헤더: KernelTraceControl.h에 선언되었습니다. KernelTraceControl.h를 포함합니다.
라이브러리: KernelTraceControl.dll에 포함되어 있습니다.