EventWriteString 함수(evntprov.h)

  • 아티클

문자열을 데이터로 포함하는 ETW 이벤트를 씁니다. 이 함수를 사용하면 안 됩니다.

구문

ULONG EVNTAPI EventWriteString(
  [in] REGHANDLE RegHandle,
  [in] UCHAR     Level,
  [in] ULONGLONG Keyword,
  [in] PCWSTR    String
);

매개 변수

[in] RegHandle

공급자의 등록 핸들입니다. 핸들은 EventRegister에서 제공됩니다. 생성된 이벤트는 핸들과 연결된 ProviderId를 사용합니다.

[in] Level

이벤트의 심각도 또는 중요도를 설명하는 데 사용되는 8비트 숫자입니다.

중요

ProviderId, Level 및 Keyword는 이벤트를 필터링하는 기본 수단입니다. 다른 종류의 필터링이 가능하지만 오버헤드가 훨씬 더 높습니다. 항상 0이 아닌 수준을 할당하고 모든 이벤트에 키워드(keyword).

이벤트 수준에 대한 자세한 내용은 EVENT_DESCRIPTOR 참조하세요.

[in] Keyword

이벤트 범주 집합에서 이벤트의 멤버 자격을 나타내는 데 사용되는 64비트 비트 마스크입니다.

중요

ProviderId, Level 및 Keyword는 이벤트를 필터링하는 기본 수단입니다. 다른 종류의 필터링이 가능하지만 오버헤드가 훨씬 더 높습니다. 항상 0이 아닌 수준을 할당하고 모든 이벤트에 키워드(keyword).

이벤트 키워드(keyword) 대한 자세한 내용은 EVENT_DESCRIPTOR 참조하세요.

[in] String

이벤트 데이터로 쓸 NUL로 종료된 문자열입니다.

반환 값

성공하거나 오류 코드가 있는 경우 ERROR_SUCCESS 반환합니다. 가능한 오류 코드에는 다음이 포함됩니다.

  • ERROR_INVALID_PARAMETER: 하나 이상의 매개 변수가 잘못되었습니다.
  • ERROR_INVALID_HANDLE: 공급자의 등록 핸들이 잘못되었습니다.
  • ERROR_ARITHMETIC_OVERFLOW: 이벤트 크기가 허용되는 최대값(64KB - 헤더)보다 큽니다.
  • ERROR_MORE_DATA: 세션 버퍼 크기가 이벤트에 비해 너무 작습니다.
  • ERROR_NOT_ENOUGH_MEMORY: 채워진 버퍼가 디스크로 플러시하려고 하지만 디스크 IO가 충분히 빠르게 발생하지 않을 때 발생합니다. 디스크가 느리고 이벤트 트래픽이 많을 때 발생합니다. 결국 더 이상 무료(빈) 버퍼가 없으며 이벤트가 삭제됩니다.
  • STATUS_LOG_FILE_FULL: 실시간 재생 파일이 가득 찼습니다. 실시간 소비자가 재생 파일의 이벤트를 사용할 때까지 이벤트는 세션에 기록되지 않습니다.

오류 코드는 주로 디버깅 및 진단 시나리오에서 사용하기 위한 것입니다. 대부분의 프로덕션 코드는 ETW 이벤트를 작성할 수 없더라도 계속 실행되고 이벤트를 계속 보고해야 하므로 릴리스 빌드는 일반적으로 오류 코드를 무시해야 합니다.

설명

이 API는 유용하지 않으며 사용하면 안 됩니다.

  • 대부분의 ETW 분석 도구는 매니페스트가 없는 문자열 전용 이벤트를 올바르게 지원하지 않습니다.
  • 매니페스트가 없으면 이벤트에 대한 중요한 정보(예: 공급자 이름, 이벤트 ID 및 이벤트 이름)를 사용할 수 없으므로 분석 도구에서 문자열 전용 이벤트를 지원하는 경우에도 결과 이벤트를 사용하기가 어렵습니다.
  • 매니페스트를 사용하면 이 함수는 단일 문자열 필드가 있는 매니페스트 기반 이벤트의 코드와 거의 동일하게 동작합니다. 그러나 매니페스트 기반 이벤트는 추적 분석 도구에서 더 잘 지원됩니다. 또한 단일 문자열 필드가 있는 이벤트에 대해 MC.exe 생성된 코드는 EventWriteString 함수보다 더 효율적입니다.

이 API를 사용하는 대신 다음 대안을 고려합니다.

  • TraceLoggingProvider.h를 사용하여 ETW 분석 도구에서 잘 지원되는 이벤트를 작성하고 매니페스트 없이 작업하며 공급자 이름 및 이벤트 이름과 같은 메타데이터를 포함합니다.
  • 계측 매니페스트를 작성합니다. 단일 NUL로 끝나는 문자열 값을 사용하여 간단한 이벤트를 만듭니다. 매니페스트 없이도 이벤트를 작성하고 수집할 수 있습니다. 수집된 추적을 디코딩하기 위한 매니페스트만 필요합니다.

EventWriteString 은 지정된 문자열로 구성된 데이터 페이로드를 사용하여 이벤트를 씁니다. 이 API는 다음 코드와 거의 동일합니다.

EVENT_DESCRIPTOR eventDescriptor;
EVENT_DATA_DESCRIPTOR dataDescriptor;
EventDescCreate(&eventDescriptor, 0, 0, 0, Level, 0, 0, Keyword);
EventDataDescCreate(&dataDescriptor, String, (wcslen(String) + 1) * sizeof(WCHAR));
return EventWrite(RegHandle, &eventDescriptor, 1, &dataDescriptor);

결과 이벤트는 결과 이벤트에 EVENT_HEADER_FLAG_STRING_ONLY 플래그 집합이 있다는 점을 제외하고 EventWrite에서 생성된 다른 이벤트와 동일합니다(이벤트 플래그에 대한 자세한 내용은 EVENT_HEADER 참조).

이벤트는 ID, 버전, Opcode, 작업 및 채널이 0으로 설정된 상태로 작성됩니다.

이벤트는 현재 스레드의 활동 ID를 사용합니다.

EVENT_HEADER_FLAG_STRING_ONLY 플래그를 인식하는 ETW 분석 도구는 디코더가 이벤트 공급자에 대한 다른 디코딩 정보를 찾을 수 없는 경우에도 문자열 값을 추출할 수 있습니다. 그러나 매니페스트가 없으면 도구에서 이벤트의 공급자 이름을 확인할 수 없습니다.

요구 사항

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

추가 정보

EventWrite

TraceLoggingProvider.h