ホーム › System.Diagnostics.Etw › EVENT_DESCRIPTOR

EVENT_DESCRIPTOR

構造体

📘 Microsoft Learn (日本語) · English

サイズx64: 16 バイト / x86: 16 バイト

サイズ=各フィールドのバイト数(x64/x86 で異なる場合は x64/x86 と併記)。x64/x86 列=フィールドのバイトオフセット(HSPで dupptr / lpoke / wpoke 等に使用)。

フィールド

フィールド型サイズ x64 x86 説明

WORD

マニフェストベースのイベントを識別するために使用される 16 ビットの数値です。

マニフェストベースの ETW では、Provider.DecodeGuid + Event.Id + Event.Version の組み合わせによってイベントが一意に識別される必要があります。つまり、DecodeGuid、Id、Version が同じイベントはすべて、フィールド名、フィールドの型、フィールドの順序に変更のない同一のフィールドセットを持つ必要があります。

マニフェストを使用しない ETW (つまり TraceLogging) では、Id フィールドは通常意味を持たず、通常は 0 に設定されます。TraceLogging イベントは一般に、イベント ID ではなくイベント名によって識別されます。

Version

BYTE

マニフェストベースのイベントのバージョンを指定するために使用される 8 ビットの数値です。

バージョンは、特定の Id を持つイベントの定義に対する改訂を示します。ある Id を持つイベントはすべて同様のセマンティクスを持つ必要がありますが、バージョンの変更は、フィールドの型の変更や新しいフィールドの追加など、イベントの詳細に対する小さな変更を示すために使用できます。

Channel

BYTE

特別なイベント処理を有効にするために使用される 8 ビットの数値です。

マニフェストベースのイベントは通常チャネル 0 を使用します。
TraceLogging ベースのイベントは通常チャネル 11 を使用します。
プロバイダー特性 (provider traits) を持つマニフェストベースのイベントは通常チャネル 12 を使用します。
その他のチャネル値は、イベントログイベントで使用される場合があります。

16 未満のチャネル値は、ETW ランタイムによる特別な扱いを有効にするために Microsoft によって予約されています。16 以上のチャネル値は ETW ランタイムでは無視され (チャネル 0 と同じように扱われます)、ユーザー定義のセマンティクスを与えることができます。

Level

BYTE

イベントの重大度または重要度を表すために使用される 8 ビットの数値です。

重要

イベントレベルは、イベントをフィルター処理するための主要な手段です。すべてのイベントに、意味のある (0 以外の) レベルを必ず割り当ててください。

レベル値 0 から 5 は Microsoft によって定義されています (evntrace.h および winmeta.h を参照してください)。レベル値 6 から 15 は予約済みです。レベル値 16 から 255 は、イベントプロバイダーが定義できます。

値	セマンティクス
LOG_ALWAYS (0)	イベントはレベルベースのイベントフィルター処理をバイパスします。イベントでこのレベルを使用しないでください。
CRITICAL (1)	重大なエラー
ERROR (2)	エラー
WARNING (3)	警告
INFO (4)	情報
VERBOSE (5)	詳細

イベント収集セッションではレベルフィルターを設定できます。これは、そのセッションが eventDescriptor.Level <= session.LevelFilter となるイベントのみを受け入れることを意味します。なお、レベルが 0 のイベントはレベルベースのフィルター処理をバイパスします。

Opcode

BYTE

特別なセマンティクスを持つイベントをマークするために使用される 8 ビットの数値です。この値は、トレースデコーダーがイベントを整理し関連付けるために使用できます。グローバルに認識される opcode 値は winmeta.h で定義されています。ほとんどのイベントは INFO (0) を使用します。opcode 値 10 から 239 には、ユーザー定義のセマンティクスを与えることができます。

opcode の START (1) と STOP (2) は、次のように ETW アクティビティの開始と終了を示すために使用されます。

通常は EventActivityIdControl を使用して、トレース内で一意となるアクティビティ ID を生成します。
opcode = START、アクティビティ ID = 生成したアクティビティ ID、関連アクティビティ ID = 親アクティビティ ID (存在する場合) として、開始イベントを書き込みます。
opcode = INFO、アクティビティ ID = 生成したアクティビティ ID として、アクティビティ情報イベントを任意の数だけ書き込みます。
opcode = STOP、アクティビティ ID = 生成したアクティビティ ID として、停止イベントを書き込みます。

これにより、トレースデコードツールはこれらのイベントをアクティビティ ID に基づいてグループに整理できます。

Task

WORD

イベントまたは関連するイベントのグループに注釈を付けるために使用される 16 ビットの数値です。

イベントのタスクコードは、プロバイダーが定義する任意の目的で使用できます。タスクコード 0 は既定値であり、そのイベントに特別なタスクコードが割り当てられていないことを示すために使用されます。ETW マニフェストでは、各タスクコードにローカライズされた文字列を割り当てることができます。タスクコードは、イベントをカテゴリにグループ化するために使用したり、単に各イベントにローカライズされた "task" 文字列を関連付けるために使用したりできます。

Keyword

ULONGLONG

イベントが一連のイベントカテゴリに属していることを示すために使用される 64 ビットのビットマスクです。

重要

イベントキーワードは、イベントをフィルター処理するための主要な手段です。すべてのイベントに、意味のある (0 以外の) キーワードを必ず割り当ててください。

キーワードの上位 16 ビット (ビットマスク 0xFFFF000000000000) は Microsoft によって定義されています。キーワードの下位 48 ビット (ビットマスク 0x0000FFFFFFFFFFFF) は、イベントプロバイダーが定義します。たとえば、イベントプロバイダーはビット 0 (ビットマスク 0x1) を "I/O" カテゴリ、ビット 1 (ビットマスク 0x2) を "UI" カテゴリ、ビット 2 (ビットマスク 0x4) を "パフォーマンス測定" カテゴリとして定義できます。このシナリオでは、あるイベントのキーワードが 0x5 に設定されている場合、そのイベントが "I/O" と "パフォーマンス測定" の両方のカテゴリに属していることを示します。

イベント収集セッションでは MatchAnyKeyword フィルターと MatchAllKeyword フィルターを設定できます。これは、そのセッションが次の式が true となるイベントのみを受け入れることを意味します。

eventDescriptor.Keyword == 0 || (
    (eventDescriptor.Keyword & session.MatchAnyKeyword) != 0 &&
    (eventDescriptor.Keyword & session.MatchAllKeyword) == session.MatchAllKeyword
)

なお、キーワードが 0 のイベントは通常、キーワードベースのフィルター処理をバイパスします。

ヒント

Windows 10 バージョン 1507 以降では、イベント収集セッションでキーワードが 0 に設定されているイベントを除外できます。これを行うには、プロバイダーを構成するときに EnableTraceEx2 に渡す ENABLE_TRACE_PARAMETERS 構造体の EnableProperty フィールドに EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0 フラグを含めます。

公式ドキュメント

EVENT_DESCRIPTOR 構造体は、ETW イベントに関する情報 (メタデータ) を格納します。

解説(Remarks)

この構造体は、イベントを書き込むために EventWrite を呼び出すときに使用します。また、イベントを生成すべきかどうか (つまり、そのイベントに関心を持つイベントリスナーが存在するかどうか) を判断するために EventEnabled を呼び出すときにも使用できます。

メモ

ほとんどのイベントプロバイダーは EVENT_DESCRIPTOR を直接使用しません。代わりに、ほとんどのイベントプロバイダーは、EventRegister、EventWriteEx、EventUnregister の呼び出しをラップする ETW フレームワークを使用して実装されます。たとえば、イベントマニフェストを記述し、メッセージコンパイラを使用してイベント用の C/C++ コードを生成したり、 TraceLogging を使用してマニフェストを不要にしたりできます。この構造体のメンバーとインストルメンテーションマニフェストとの対応の詳細については、 EventDefinitionType 複合型の属性を参照してください。

この構造体は、 ProcessTrace と EventRecordCallback コールバックを使用してイベントを消費するときに、イベントレコードとともに返される EVENT_HEADER 構造体に含まれています。

メモ

MOF ベースのイベントを処理する場合、イベントの識別情報は Id フィールドではなく Opcode フィールドに含まれています。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での定義

#include <windows.h>

// EVENT_DESCRIPTOR  (x64 16 / x86 16 バイト)
typedef struct EVENT_DESCRIPTOR {
    WORD Id;
    BYTE Version;
    BYTE Channel;
    BYTE Level;
    BYTE Opcode;
    WORD Task;
    ULONGLONG Keyword;
} EVENT_DESCRIPTOR;

using System;
using System.Runtime.InteropServices;

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
public struct EVENT_DESCRIPTOR
{
    public ushort Id;
    public byte Version;
    public byte Channel;
    public byte Level;
    public byte Opcode;
    public ushort Task;
    public ulong Keyword;
}

Imports System.Runtime.InteropServices

<StructLayout(LayoutKind.Sequential, CharSet:=CharSet.Unicode)>
Public Structure EVENT_DESCRIPTOR
    Public Id As UShort
    Public Version As Byte
    Public Channel As Byte
    Public Level As Byte
    Public Opcode As Byte
    Public Task As UShort
    Public Keyword As ULong
End Structure

import ctypes
from ctypes import wintypes

class EVENT_DESCRIPTOR(ctypes.Structure):
    _fields_ = [
        ("Id", ctypes.c_ushort),
        ("Version", ctypes.c_ubyte),
        ("Channel", ctypes.c_ubyte),
        ("Level", ctypes.c_ubyte),
        ("Opcode", ctypes.c_ubyte),
        ("Task", ctypes.c_ushort),
        ("Keyword", ctypes.c_ulonglong),
    ]

#[repr(C)]
pub struct EVENT_DESCRIPTOR {
    pub Id: u16,
    pub Version: u8,
    pub Channel: u8,
    pub Level: u8,
    pub Opcode: u8,
    pub Task: u16,
    pub Keyword: u64,
}

import "golang.org/x/sys/windows"

type EVENT_DESCRIPTOR struct {
	Id uint16
	Version byte
	Channel byte
	Level byte
	Opcode byte
	Task uint16
	Keyword uint64
}

type
  EVENT_DESCRIPTOR = record
    Id: Word;
    Version: Byte;
    Channel: Byte;
    Level: Byte;
    Opcode: Byte;
    Task: Word;
    Keyword: UInt64;
  end;

const EVENT_DESCRIPTOR = extern struct {
    Id: u16,
    Version: u8,
    Channel: u8,
    Level: u8,
    Opcode: u8,
    Task: u16,
    Keyword: u64,
};

type
  EVENT_DESCRIPTOR {.bycopy.} = object
    Id: uint16
    Version: uint8
    Channel: uint8
    Level: uint8
    Opcode: uint8
    Task: uint16
    Keyword: uint64

struct EVENT_DESCRIPTOR
{
    ushort Id;
    ubyte Version;
    ubyte Channel;
    ubyte Level;
    ubyte Opcode;
    ushort Task;
    ulong Keyword;
}

HSP用定義

HSP3.7/3.8 は構造体機能が無いため4byte整数配列(dim)+peek/poke で操作(32/64bitでサイズ・位置が異なる場合はタブで分割)。IronHSP は NSTRUCT(#defstruct/stdim/->)で32/64bit共通。

; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x64 レイアウト)
; EVENT_DESCRIPTOR サイズ: 16 バイト(x64)
dim st, 4    ; 4byte整数×4(構造体サイズ 16 / 4 切り上げ)
; Id : WORD (+0, 2byte)  wpoke st,0,値  /  値 = wpeek(st,0)
; Version : BYTE (+2, 1byte)  poke st,2,値  /  値 = peek(st,2)
; Channel : BYTE (+3, 1byte)  poke st,3,値  /  値 = peek(st,3)
; Level : BYTE (+4, 1byte)  poke st,4,値  /  値 = peek(st,4)
; Opcode : BYTE (+5, 1byte)  poke st,5,値  /  値 = peek(st,5)
; Task : WORD (+6, 2byte)  wpoke st,6,値  /  値 = wpeek(st,6)
; Keyword : ULONGLONG (+8, 8byte)  qpoke st,8,値 / qpeek(st,8)  ※IronHSPのみ。3.7/3.8は lpoke st,8,下位 : lpoke st,12,上位
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。

; IronHSP は NSTRUCT(構造体)をサポート。32bit/64bit どちらでも同じコードで動作します。
#defstruct global EVENT_DESCRIPTOR
    #field short Id
    #field byte Version
    #field byte Channel
    #field byte Level
    #field byte Opcode
    #field short Task
    #field int64 Keyword
#endstruct

stdim st, EVENT_DESCRIPTOR        ; NSTRUCT 変数を確保
st->Id = 100
mes "Id=" + st->Id

EVENT_DESCRIPTOR

フィールド

公式ドキュメント

解説(Remarks)

各言語での定義

HSP用 定義

HSP用定義