EVENT_TRACE_LOGFILEA 구조체(evntrace.h)

아티클
08/23/2023

EVENT_TRACE_LOGFILE 구조는 추적 데이터 원본에 대한 정보를 저장합니다.

EVENT_TRACE_LOGFILE 구조체는 OpenTrace를 호출할 때 사용됩니다. 사용자는 추적 데이터 원본(ETL 파일의 이름 또는 활성 실시간 로거 세션의 이름), 추적 처리 플래그 및 추적 데이터를 수신할 콜백 함수에 대한 정보가 포함된 EVENT_TRACE_LOGFILE 구조를 제공합니다. 성공하면 OpenTrace 는 구조체의 나머지 필드를 채워 추적 데이터 원본에 대한 세부 정보를 반환합니다.

ProcessTrace는 버퍼를 처리할 때 EVENT_TRACE_LOGFILE 구조로 사용자 정의 BufferCallback을 호출하여 이벤트 처리 세션 및 버퍼에 대한 정보를 제공합니다.

구문

typedef struct _EVENT_TRACE_LOGFILEA {
  LPSTR                         LogFileName;
  LPSTR                         LoggerName;
  LONGLONG                      CurrentTime;
  ULONG                         BuffersRead;
  union {
    ULONG LogFileMode;
    ULONG ProcessTraceMode;
  } DUMMYUNIONNAME;
  EVENT_TRACE                   CurrentEvent;
  TRACE_LOGFILE_HEADER          LogfileHeader;
  PEVENT_TRACE_BUFFER_CALLBACKA BufferCallback;
  ULONG                         BufferSize;
  ULONG                         Filled;
  ULONG                         EventsLost;
  union {
    PEVENT_CALLBACK        EventCallback;
    PEVENT_RECORD_CALLBACK EventRecordCallback;
  } DUMMYUNIONNAME2;
  ULONG                         IsKernelTrace;
  PVOID                         Context;
} EVENT_TRACE_LOGFILEA, *PEVENT_TRACE_LOGFILEA;

멤버

LogFileName

처리 중인 로그 파일의 이름 또는 실시간 추적 세션에서 데이터를 처리하는 경우 NULL 입니다. OpenTrace를 호출하여 로그 파일의 데이터를 사용하는 경우 이 멤버의 값을 지정합니다.

OpenTrace를 호출할 때 LoggerName이 NULL이 아닌 경우 LogFileName은 NULL이어야 합니다.

OpenTrace를 호출할 때 이벤트를 사용하는 사용자에게는 파일을 읽을 수 있는 권한이 있어야 합니다.

참고

LogFileName 필드를 통해 OpenTrace에 제공된 파일 이름은 접미사를 포함한 전체 파일 이름이어야 합니다. 일부 추적 파일 만들기 API는 사용자가 지정한 파일 이름에 접미사를 자동으로 추가할 수 있습니다. 예를 들어 컨트롤러가 프라이빗 세션에 이벤트를 기록하는 경우(컨트롤러가 StartTrace를 호출할 때 EVENT_TRACE_PROPERTIESLogFileMode 멤버를 EVENT_TRACE_PRIVATE_LOGGER_MODE 설정) 생성된 ETL 파일에는 프로세스 ID 접미사(예: )가 포함됩니다. mytrace.etl_123 EVENT_TRACE_FILE_MODE_NEWFILE 모드를 사용하여 파일을 만든 경우에도 발생할 수 있습니다. 이 경우 생성된 ETL 파일에 시퀀스 번호가 포함됩니다.

LoggerName

실시간 이벤트 추적 세션의 이름 또는 로그 파일에서 데이터를 처리하는 경우 NULL 입니다. OpenTrace를 호출하여 실시간 세션의 데이터를 사용하는 경우 이 멤버의 값을 지정합니다.

OpenTrace를 호출할 때 LogFileName이 NULL이 아닌 경우 LoggerName은 NULL이어야 합니다.

추적 컨트롤러가 EVENT_TRACE_REAL_TIME_MODE 플래그를 포함하도록 EVENT_TRACE_PROPERTIESLogFileMode 멤버를 설정한 경우에만 이벤트를 실시간으로 사용할 수 있습니다.

관리자 권한이 있는 사용자, 성능 로그 사용자 그룹의 사용자 및 LocalSystem, LocalService, NetworkService로 실행되는 애플리케이션만 실시간으로 이벤트를 사용할 수 있습니다. 제한된 사용자에게 이벤트를 실시간으로 사용할 수 있는 기능을 부여하려면 성능 로그 사용자 그룹에 추가하거나 EventAccessControl을 호출합니다.

Windows XP 및 Windows 2000: 누구나 실시간 이벤트를 사용할 수 있습니다.

CurrentTime

출력에서 현재 시간(1601년 1월 1일 자정 이후 100나노초 간격)입니다.

BuffersRead

출력에서 처리된 버퍼의 수입니다.

DUMMYUNIONNAME

DUMMYUNIONNAME.LogFileMode

예약되어 있습니다. 사용하지 마십시오.

DUMMYUNIONNAME.ProcessTraceMode

이벤트 처리를 위한 모드입니다. 모드는 헤더 파일에 정의 evntcons.h 됩니다. 다음 모드 중 하나 이상을 지정할 수 있습니다.

PROCESS_TRACE_MODE_EVENT_RECORD

새 EVENT_RECORD 형식으로 이벤트를 수신하려면 이 모드를 지정합니다(적극 권장). 새 형식으로 이벤트를 수신하려면 EventRecordCallback 멤버에서 콜백을 지정해야 합니다. 이 모드를 지정하지 않으면 EventCallback 멤버에 지정된 콜백을 통해 이전 형식의 이벤트를 받게 됩니다.

Windows Vista 이전: 지원되지 않습니다.
PROCESS_TRACE_MODE_RAW_TIMESTAMP

기본적으로 ProcessTrace 는 이벤트의 TimeStamp 를 원래 원시 형식(시스템 시간, QPC 시간 또는 CPU 주기 카운터)에서 시스템 시간(1601년 1월 1일 자정 이후 100나노초 간격)으로 변환합니다.

EVENT_HEADERTimeStamp 멤버에서 타임스탬프 값을 사용하지 않으려면 PROCESS_TRACE_MODE_RAW_TIMESTAMP 플래그를 지정하고 시스템 시간으로 변환하지 EVENT_TRACE_HEADER. 이 플래그를 지정하면 ProcessTrace는 컨트롤러가 EVENT_TRACE_PROPERTIESWnode.ClientContext 멤버에 지정한 원래 형식으로 타임스탬프를 그대로 둡니다.

Windows Vista 이전: 지원되지 않습니다.
PROCESS_TRACE_MODE_REAL_TIME

이벤트를 실시간으로 수신하려면 이 모드를 지정합니다. LoggerName이 NULL이 아닌 경우 이 모드를 지정해야 합니다.

CurrentEvent

출력에서 마지막으로 처리된 이벤트를 포함하는 EVENT_TRACE 구조체입니다.

LogfileHeader

출력에서 세션 및 세션이 실행된 컴퓨터에 대한 일반 정보가 포함된 TRACE_LOGFILE_HEADER 구조체입니다.

BufferCallback

각 버퍼 ETW 플러시에 대한 버퍼 관련 통계를 수신하는 BufferCallback 함수에 대한 포인터입니다. ETW는 버퍼의 모든 이벤트를 전달한 후 이 콜백을 호출합니다. 이 콜백은 선택 사항입니다.

BufferSize

출력에서 에는 각 버퍼의 크기(바이트)가 포함됩니다.

Filled

출력에서 는 유효한 정보를 포함하는 버퍼의 바이트 수를 포함합니다.

EventsLost

사용되지 않습니다.

DUMMYUNIONNAME2

DUMMYUNIONNAME2.EventCallback

ETW가 버퍼의 각 이벤트에 대해 호출하는 EventCallback 함수에 대한 포인터입니다. 이 필드는 ProcessTraceMode 필드에 플래그가 포함되지 PROCESS_TRACE_MODE_EVENT_RECORD 않은 경우에만 사용됩니다.

참고

ProcessTraceMode 필드에 플래그가 포함된 경우 EventCallback 필드는 EventRecordCallback으로 PROCESS_TRACE_MODE_EVENT_RECORD 처리됩니다. EventCallback이 ProcessTrace에서 왜곡된 데이터를 수신하는 경우 ProcessTraceMode 필드에 플래그가 PROCESS_TRACE_MODE_EVENT_RECORD 포함되어 있지 않은지 확인합니다.

팁

새 코드는 EventCallback 대신 EventRecordCallback을 사용해야 합니다. EventRecordCallback은 보다 완전한 이벤트 정보를 포함하는 EVENT_RECORD 수신하고, TdhGetEventInformation과 같은 디코딩 API와 함께 사용할 수 있으며, 콜백에서 사용할 수 있는 컨텍스트 포인터가 있습니다.

DUMMYUNIONNAME2.EventRecordCallback

ETW가 버퍼의 각 이벤트에 대해 호출하는 EventRecordCallback 함수에 대한 포인터입니다. 이 필드는 ProcessTraceMode 필드에 플래그가 포함된 PROCESS_TRACE_MODE_EVENT_RECORD 경우에만 사용됩니다.

참고

ProcessTraceMode 필드에 플래그가 포함되지 PROCESS_TRACE_MODE_EVENT_RECORD 않은 경우 EventRecordCallback 필드는 EventCallback으로 처리됩니다. EventRecordCallback이 ProcessTrace에서 왜곡된 데이터를 수신하는 경우 ProcessTraceMode 필드에 플래그가 PROCESS_TRACE_MODE_EVENT_RECORD 포함되어 있는지 확인합니다.

Windows Vista 이전: 지원되지 않습니다.

IsKernelTrace

출력에서 이 멤버가 TRUE이면 이벤트 추적 세션은 NT 커널 로거입니다. 그렇지 않으면 다른 이벤트 추적 세션입니다.

Context

소비자가 OpenTrace를 호출할 때 지정할 수 있는 컨텍스트 데이터입니다. 소비자가 EventRecordCallback을 사용하여 이벤트를 사용하는 경우 ETW는 EVENT_RECORD 구조체의 UserContext 멤버를 이 값으로 설정합니다.

Windows Vista 이전: 지원되지 않습니다.

설명

이벤트 소비자는 다음을 수행해야 합니다.

이 구조체의 메모리를 0으로 초기화합니다.
ETL 파일에서 읽는 경우 LogFileName 을 파일의 경로로 설정합니다. 그렇지 않으면(즉, 실시간 세션에서 읽는 경우) LoggerName 을 세션 이름으로 설정하고 ProcessTraceMode 를 로 PROCESS_TRACE_MODE_REAL_TIME설정합니다.
EventRecordCallback(권장)을 사용하는 경우 EventRecordCallback을 이벤트 레코드 콜백 함수의 주소로 설정하고, 컨텍스트를 콜백에 제공할 값으로 설정하고, ProcessTraceMode에 추가 PROCESS_TRACE_MODE_EVENT_RECORD 합니다. 그렇지 않으면(예: EventCallback을 사용하는 경우) EventCallback 을 이벤트 콜백 함수의 주소로 설정합니다.
각 버퍼가 처리된 후 콜백이 필요한 경우 BufferCallback 을 버퍼 콜백 함수의 주소로 설정합니다.
처리된 타임스탬프 대신 원래 원시 타임스탬프 데이터를 원하는 경우 ProcessTraceMode에 를 추가 PROCESS_TRACE_MODE_RAW_TIMESTAMP 합니다.
OpenTrace를 호출합니다. 성공하면 OpenTrace 함수는 이 구조체의 멤버를 추적 데이터 원본의 정보로 채웁니다.
OpenTrace에서 반환된 핸들을 사용하여 ProcessTrace를 호출합니다.
- ProcessTrace 는 각 이벤트에 대한 이벤트 콜백 함수를 호출합니다.
- ProcessTrace는 각 버퍼를 완료한 후 버퍼 콜백 함수(제공된 경우)를 호출하고 추적 처리 상태 정보가 포함된 EVENT_TRACE_LOGFILE 구조체의 instance 포함합니다.
추적 처리가 완료되면 CloseTrace 를 호출하여 OpenTrace에서 반환된 핸들을 닫습니다.

참고

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

요구 사항


지원되는 최소 클라이언트	Windows 2000 Professional[데스크톱 앱만]
지원되는 최소 서버	Windows 2000 Server[데스크톱 앱만]
머리글	evntrace.h

참고 항목

BufferCallback

EventRecordCallback

OpenTrace

다음을 통해 공유

EVENT_TRACE_LOGFILEA 구조체(evntrace.h)

구문

멤버

설명

요구 사항

참고 항목

피드백

추가 리소스