マニフェストベースのイベントの記述

[アーティクル]
06/13/2023

トレースセッションにイベントを書き込む前に、プロバイダーを登録する必要があります。プロバイダーを登録すると、プロバイダーがトレースセッションにイベントを書き込む準備ができていることが ETW に通知されます。プロセスでは、最大 1,024 個のプロバイダー GUID を登録できます。ただし、プロセスで登録するプロバイダーの数を 1 つまたは 2 つに制限する必要があります。

Windows Vista より前: プロセスで登録できるプロバイダーの数に制限はありません。

マニフェストベースのプロバイダーを登録するには、 EventRegister 関数を呼び出します。この関数は、プロバイダーの GUID を登録し、コントローラーがプロバイダーを有効または無効にしたときに ETW が呼び出すオプションのコールバックを識別します。

プロバイダーが終了する前に、 EventUnregister 関数を呼び出して、プロバイダーの登録を ETW から削除します。 EventRegister 関数は、EventUnregister 関数に渡す登録ハンドルを返します。

マニフェストベースのプロバイダーは、セッションでプロバイダーを有効または無効にしたときに通知を受信するために EnableCallback 関数を実装する必要はありません。コールバックは省略可能であり、情報提供のために使用されます。プロバイダーを登録するときにコールバックを指定または実装する必要はありません。マニフェストベースのプロバイダーは単にイベントを書き込むことができます。ETW はイベントがトレースセッションに記録されるかどうかを決定します。イベントでイベントのデータを生成するために広範な作業を実行する必要がある場合は、 まず EventEnabled または EventProviderEnabled 関数を呼び出して、作業を実行する前にイベントがセッションに書き込まれるかどうかを確認できます。

通常、プロバイダーがプロバイダー定義のフィルターデータ (EnableCallback の FilterData パラメーターを参照) をプロバイダーに渡す必要がある場合、またはプロバイダーが自身の登録時に指定したコンテキスト情報を使用する場合は、コールバックを実装します (EventRegister の CallbackContext パラメーターを参照)。

マニフェストベースのプロバイダーは、 EventWrite または EventWriteString 関数を呼び出して、セッションにイベントを書き込みます。イベントデータが文字列である場合、またはプロバイダーのマニフェストを定義せず、イベントデータが 1 つの文字列である場合は、 EventWriteString 関数を呼び出してイベントを書き込みます。数値データ型または複合データ型を含むイベントデータの場合は、 EventWrite 関数を呼び出してイベントをログに記録します。

次の例は、 EventWrite 関数を使用して書き込まれるイベントデータを準備する方法を示しています。この例では、マニフェストベースのプロバイダーのイベントスキーマの発行に関するページで定義されているイベントを参照しています。

#include <windows.h>
#include <stdio.h>
#include <evntprov.h>
#include "provider.h"  // Generated from manifest

#define SUNDAY     0X1
#define MONDAY     0X2
#define TUESDAY    0X4
#define WEDNESDAY  0X8
#define THURSDAY   0X10
#define FRIDAY     0X20
#define SATURDAY   0X40

enum TRANSFER_TYPE {
  Download = 1,
  Upload,
  UploadReply
};

#define MAX_NAMEDVALUES          5  // Maximum array size
#define MAX_PAYLOAD_DESCRIPTORS  9 + (2 * MAX_NAMEDVALUES)

typedef struct _namedvalue {
  LPWSTR name;
  USHORT value;
} NAMEDVALUE, *PNAMEDVALUE;

void wmain(void)
{
    DWORD status = ERROR_SUCCESS;
    REGHANDLE RegistrationHandle = NULL; 
    EVENT_DATA_DESCRIPTOR Descriptors[MAX_PAYLOAD_DESCRIPTORS]; 
    DWORD i = 0;

    // Data to load into event descriptors

    USHORT Scores[3] = {45, 63, 21};
    ULONG pImage = (ULONG)&Scores;
    DWORD TransferType = Upload;
    DWORD Day = MONDAY | TUESDAY;
    LPWSTR Path = L"c:\\path\\folder\\file.ext";
    BYTE Cert[11] = {0x2, 0x4, 0x8, 0x10, 0x20, 0x30, 0x40, 0x50, 0x60, 0x0, 0x1};
    PBYTE Guid = (PBYTE) &ProviderGuid;
    USHORT ArraySize = MAX_NAMEDVALUES;
    BOOL IsLocal = TRUE;
    NAMEDVALUE NamedValues[MAX_NAMEDVALUES] = { 
        {L"Bill", 1},
        {L"Bob", 2},
        {L"William", 3},
        {L"Robert", 4},
        {L"", 5}
        };

    status = EventRegister(
        &ProviderGuid,      // GUID that identifies the provider
        NULL,               // Callback not used
        NULL,               // Context noot used
        &RegistrationHandle // Used when calling EventWrite and EventUnregister
        );

    if (ERROR_SUCCESS != status)
    {
        wprintf(L"EventRegister failed with %lu\n", status);
        goto cleanup;
    }
  
    // Load the array of data descriptors for the TransferEvent event. 
    // Add the data to the array in the order of the <data> elements
    // defined in the event's template. 
   
    EventDataDescCreate(&Descriptors[i++], &pImage, sizeof(ULONG));
    EventDataDescCreate(&Descriptors[i++], Scores, sizeof(Scores));
    EventDataDescCreate(&Descriptors[i++], Guid, sizeof(GUID));
    EventDataDescCreate(&Descriptors[i++], Cert, sizeof(Cert));
    EventDataDescCreate(&Descriptors[i++], &IsLocal, sizeof(BOOL));
    EventDataDescCreate(&Descriptors[i++], Path, (ULONG)(wcslen(Path) + 1) * sizeof(WCHAR));
    EventDataDescCreate(&Descriptors[i++], &ArraySize, sizeof(USHORT));

    // If your event contains a structure, you should write each member
    // of the structure separately. If the structure contained integral data types
    // such as DWORDs and the data types were aligned on an 8-byte boundary, you 
    // could use the following call to write the structure, however, you are 
    // encouraged to write the members separately.
    //
    // EventDataDescCreate(&EvtData, struct, sizeof(struct));
    //
    // Because the array of structures in this example contains both strings 
    // and numbers, you must write each member of the structure separately.

    for (int j = 0; j < MAX_NAMEDVALUES; j++)
    {
        EventDataDescCreate(&Descriptors[i++], NamedValues[j].name, (ULONG)(wcslen(NamedValues[j].name)+1) * sizeof(WCHAR) );
        EventDataDescCreate(&Descriptors[i++], &(NamedValues[j].value), sizeof(USHORT) );
    }

    EventDataDescCreate(&Descriptors[i++], &Day, sizeof(DWORD));
    EventDataDescCreate(&Descriptors[i++], &TransferType, sizeof(DWORD));

    // Write the event. You do not have to verify if your provider is enabled before
    // writing the event. ETW will write the event to any session that enabled
    // the provider. If no session enabled the provider, the event is not 
    // written. If you need to perform extra work to write an event that you
    // would not otherwise do, you may want to call the EventEnabled function
    // before performing the extra work. The EventEnabled function tells you if a
    // session has enabled your provider, so you know if you need to perform the 
    // extra work or not.

    status = EventWrite(
        RegistrationHandle,              // From EventRegister
        &TransferEvent,                  // EVENT_DESCRIPTOR generated from the manifest
        (ULONG)MAX_PAYLOAD_DESCRIPTORS,  // Size of the array of EVENT_DATA_DESCRIPTORs
        &Descriptors[0]                  // Array of descriptors that contain the event data
        );

    if (status != ERROR_SUCCESS) 
    {
        wprintf(L"EventWrite failed with 0x%x", status);
    }

cleanup:

    EventUnregister(RegistrationHandle);
}

上記の例で使用しているマニフェスト ( インストルメンテーションマニフェストのコンパイルを参照) をコンパイルすると、次のヘッダーファイルが作成されます (上記の例で参照)。

//**********************************************************************`
//* This is an include file generated by Message Compiler.             *`
//*                                                                    *`
//* Copyright (c) Microsoft Corporation. All Rights Reserved.          *`
//**********************************************************************`
#pragma once
//+
// Provider Microsoft-Windows-ETWProvider Event Count 1
//+
EXTERN_C __declspec(selectany) const GUID ProviderGuid = {0xd8909c24, 0x5be9, 0x4502, {0x98, 0xca, 0xab, 0x7b, 0xdc, 0x24, 0x89, 0x9d}};
//
// Keyword
//
#define READ_KEYWORD 0x1
#define WRITE_KEYWORD 0x2
#define LOCAL_KEYWORD 0x4
#define REMOTE_KEYWORD 0x8

//
// Event Descriptors
//
EXTERN_C __declspec(selectany) const EVENT_DESCRIPTOR TransferEvent = {0x1, 0x0, 0x0, 0x4, 0x0, 0x0, 0x5};
#define TransferEvent_value 0x1
#define MSG_Provider_Name                    0x90000001L
#define MSG_Event_WhenToTransfer             0xB0000001L
#define MSG_Map_Download                     0xD0000001L
#define MSG_Map_Upload                       0xD0000002L
#define MSG_Map_UploadReply                  0xD0000003L
#define MSG_Map_Sunday                       0xF0000001L
#define MSG_Map_Monday                       0xF0000002L
#define MSG_Map_Tuesday                      0xF0000003L
#define MSG_Map_Wednesday                    0xF0000004L
#define MSG_Map_Thursday                     0xF0000005L
#define MSG_Map_Friday                       0xF0000006L
#define MSG_Map_Saturday                     0xF0000007L

次の方法で共有

マニフェストベースのイベントの記述

フィードバック

その他のリソース