다음을 통해 공유

TraceLoggingCustom 매크로(traceloggingprovider.h)

  • 아티클

사용자 지정 serializer를 사용하여 압축된 필드를 이벤트에 추가하는 TraceLogging 래퍼 매크로입니다.

대부분의 TraceLogging 이벤트는 사용자 지정 serializer를 사용할 필요가 없으며 TraceLoggingCustom을 사용하면 안 됩니다.

구문

void TraceLoggingCustom(
  [in]            pValue,
  [in]            cbValue,
  [in]            protocol,
  [in]            bSchema,
  [in]            cbSchema,
  [in, optional]  __VA_ARGS__
);

매개 변수

[in] pValue

지정된 프로토콜 패밀리의 serializer에 의해 런타임에 직렬화된 필드의 페이로드에 대한 포인터입니다.

[in] cbValue

지정된 프로토콜 패밀리의 serializer에 의해 런타임 시 직렬화된 필드 페이로드의 크기(바이트)입니다.

[in] protocol

0-4의 Microsoft 정의 값 또는 5-31의 사용자 정의 값일 수 있는 프로토콜 패밀리입니다. Microsoft에서 정의한 값은 로 시작하는 TRACELOGGING_PROTOCOL_매크로로 정의됩니다.

[in] bSchema

프로토콜 정의 형식으로 페이로드(즉, 스키마)를 디코딩하는 데 필요한 정보를 포함하는 쉼표로 구분된 바이트 값 목록입니다. 이 목록의 값은 컴파일 시간 상수여야 합니다. 예: (0x12, 0x23, 0x34)

[in] cbSchema

bSchema에 제공된 바이트 값의 수입니다. 이 값은 컴파일 시간 상수여야 합니다.

[in, optional] __VA_ARGS__

필드 정의에 대한 선택적 이름, 설명 및 태그 매개 변수입니다.

TraceLoggingCustom은 5, 6, 7 또는 8 매개 변수로 지정할 수 있습니다. 매개 변수를 지정하지 않으면 기본값이 사용됩니다. 예를 들어 TraceLoggingCustom(&x.data, sizeof(x.data), p, (schema), cbSchema)는 TraceLoggingCustom(&x.data, sizeof(x.data), p, (schema), cbSchema, "&x.data", "", 0)와 같습니다.

  • [in, optional] name

    이벤트 필드에 사용할 이름입니다. 제공된 경우 name 매개 변수는 문자열 리터럴(변수 아님)이어야 하며 '\0' 문자를 포함하지 않아야 합니다. 제공되지 않으면 이벤트 필드 이름은 pValue를 기반으로 합니다.

  • [in, optional] description

    이벤트 필드 값에 대한 설명입니다. 제공된 경우 description 매개 변수는 문자열 리터럴이어야 하며 PDB에 포함됩니다.

  • [in, optional] tags

    컴파일 시간 상수 정수 값입니다. 낮은 28비트 값은 필드의 메타데이터에 포함됩니다. 이 값의 의미 체계는 이벤트 소비자에 의해 정의됩니다. 이벤트 처리 중에 이 값은 EVENT_PROPERTY_INFO 태그 필드에서 검색할 수 있습니다.

반환 값

없음

설명

TraceLoggingCustom(pValue, cbValue, protocol, (schema...), cbSchema, ...)는 TraceLoggingWrite 매크로 호출에 대한 매개 변수로 사용할 수 있습니다. 각 TraceLoggingCustom 매개 변수는 사용자 지정 직렬화된 필드를 이벤트에 추가합니다. 대부분의 TraceLogging 이벤트는 사용자 지정 직렬 변환기를 사용하지 않으며 TraceLoggingCustom을 사용하면 안 됩니다. 범용 ETW 디코더는 사용자 지정 serialization을 사용하는 필드를 지원하지 않으며 일반적으로 필드를 TDH_INTYPE_BINARY 처리합니다.

디코더는 TDH API를 사용하여 TraceLoggingCustom 직렬화된 필드에 액세스해야 합니다. TdhGetEventInformation에서 반환된 TRACE_EVENT_INFO 구조체에는 기록된 TraceLoggingCustom 필드와 관련된 두 개의 EVENT_PROPERTY_INFO 구조체가 포함됩니다. 이는 일반적인 방식으로 이진 필드(TDH_INTYPE_BINARY)에 대한 EVENT_RECORD UserData Blob에 있는 데이터와 상관 관계가 있습니다.

  • 두 EVENT_PROPERTY_INFO 구조체 중 첫 번째는 직렬화된 페이로드의 길이(예: cbValue)를 설명하는 "Length" 속성입니다.
  • 두 번째는 사용자의 페이로드(pbValue)를 참조하는 속성입니다. 두 번째 속성에는 PropertyParamLength("Length" 속성 참조) 및 PropertyHasCustomSchema 집합이 있습니다.

디코더는 PropertyHasCustomSchema가 설정되었음을 인식하고 프로토콜 형식 및 프로토콜 메타데이터가 있는 TRACE_EVENT_INFORMATION 오프셋인 CustomSchemaOffset에 대해 EVENT_PROPERTY_INFO customSchemaType 멤버를 참조해야 합니다. 이 경우 형식(의사 구조체)으로 전달한 메타데이터를 찾을 수 있습니다.

struct _CUSTOM_SCHEMA {
    UINT16 protocolType;
    UINT16 cbSchema;
    BYTE bSchema[cbSchema];
};

PropertyHasCustomSchema 플래그를 인식하기 위해 이러한 추가 단계를 수행하지 않고 대신 EVENT_PROPERTY_INFO 공용 구조체의 nonStructType 부분을 참조하여 이벤트를 디코딩하는 기존 디코더는 페이로드를 TDH_INTYPE_BINARY 것처럼 원활하게 처리합니다.

예제

// Value generated at runtime by serializer:
BYTE rgValue[] = {...};

TraceLoggingWrite(
   g_hProvider,
   "MyEventName",
   TraceLoggingCustom(
      rgValue,
      sizeof(rgValue),
      TRACELOGGING_PROTOCOL_MYPROTOCOL,
      ( 0x0, 0x1, 0x2 ), // Generated at compile-time
      3,
      "MyCustomField"),
   TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
   TraceLoggingKeyword(MyEventCategories)); // Provider-defined categories

요구 사항

   
지원되는 최소 클라이언트 Windows Vista [데스크톱 앱 | UWP 앱]
지원되는 최소 서버 Windows Server 2008 [데스크톱 앱 | UWP 앱]
대상 플랫폼 Windows
헤더 traceloggingprovider.h

추가 정보

TraceLoggingWrite

추적 로깅 래퍼 매크로