Win32 API 日本語リファレンス
ホームSystem.Diagnostics.Etw › ENABLE_TRACE_PARAMETERS

ENABLE_TRACE_PARAMETERS

構造体
サイズx64: 48 バイト / x86: 36 バイト

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

フィールド

フィールドサイズx64x86説明
VersionDWORD4+0+0ENABLE_TRACE_PARAMETERS_VERSION_2 (2) に設定します。
EnablePropertyDWORD4+4+4

イベントの書き込み時に ETW が含めることができる省略可能な設定です。一部の設定では、 各イベントの 拡張データ項目 セクションに追加のデータが書き込まれます。それ以外の設定は、トレースに含めるイベントを 制御します。これらの省略可能な設定を使用するには、次のフラグのうち 1 つ以上を指定します。 使用しない場合は 0 に設定します。

  • EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0

    イベントのキーワードが 0 であるイベントを除外します。

    Windows 10 バージョン 1507 以降でサポートされます。修正プログラムを適用すれば Windows 8.1 および Windows 7 SP1 でもサポートされます。

  • EVENT_ENABLE_PROPERTY_PROVIDER_GROUP

    この EnableTraceEx2 の呼び出しが、個々のイベント プロバイダーではなく プロバイダー グループ を有効にすることを示します。

    Windows 10 バージョン 1507 以降でサポートされます。修正プログラムを適用すれば Windows 8.1 および Windows 7 SP1 でもサポートされます。

  • EVENT_ENABLE_PROPERTY_PROCESS_START_KEY

    拡張データにプロセス開始キーを含めます。

    プロセス開始キーは、プロセスを識別するシーケンス番号です。プロセス ID は セッション内で再利用される可能性がありますが、プロセス開始キーは現在の ブート セッション内で一意であることが保証されます。

    Windows 10 バージョン 1507 以降でサポートされます。修正プログラムを適用すれば Windows 8.1 および Windows 7 SP1 でもサポートされます。

  • EVENT_ENABLE_PROPERTY_EVENT_KEY

    拡張データにイベント キーを含めます。

    イベント キーは、イベント インスタンスを一意に識別する識別子であり、この イベントをリッスンしている複数のトレース セッション間で同じ値になります。 同時に実行されているトレース セッションの相関付けに使用できます。

    Windows 10 バージョン 1507 以降でサポートされます。

  • EVENT_ENABLE_PROPERTY_EXCLUDE_INPRIVATE

    InPrivate イベントとしてマークされているイベント、または InPrivate として マークされているプロセスから送信されたイベントをすべて除外します。

    InPrivate は、そのイベントまたはプロセスがプライベートまたは個人的と見なされる データを含んでいることを意味します。これが機能するかどうかは、プロセスまたは イベント自身が自らを InPrivate として指定するかどうかによります。

    Windows 10 バージョン 1507 以降でサポートされます。

  • EVENT_ENABLE_PROPERTY_SID

    イベントの拡張データに、ユーザーのセキュリティ識別子 (SID) を含めます。

    Windows Vista 以降でサポートされます。

  • EVENT_ENABLE_PROPERTY_TS_ID

    イベントの拡張データに、ターミナル セッション識別子を含めます。

    Windows Vista 以降でサポートされます。

  • EVENT_ENABLE_PROPERTY_STACK_TRACE

    EventWrite を使用して書き込まれたイベントの拡張データに、呼び出しスタックのトレースを 追加します。

    メモ

    イベント全体のサイズが 64K を超えると、ETW はそのイベントを破棄します。 プロバイダーが最大値の 64K に近いサイズのイベントを記録している場合、 スタックのキャプチャを有効にするとイベントが失われる可能性があります。

    スタックがフレームの最大数 (192) より長い場合、超過したフレームはスタックの 末尾から切り捨てられます。

    コンシューマー側では、イベントに EVENT_EXTENDED_ITEM_STACK_TRACE32 または EVENT_EXTENDED_ITEM_STACK_TRACE64 拡張項目が含まれます。64 ビット コンピューターでは、32 ビットのトレース コントローラーによってトレースが開始された場合でも、トレースには 64 ビットの スタックが含まれる点に注意してください。

    Windows 7 以降でサポートされます。

ControlFlagsDWORD4+8+8予約済みです。0 に設定します。
SourceIdGUID16+12+12プロバイダーを有効または無効にする呼び出し元を一意に識別する GUID です。 プロバイダーが EnableCallback を実装していない場合、この GUID は使用されません。
EnableFilterDescEVENT_FILTER_DESCRIPTOR*8/4+32+28フィルター データを指す EVENT_FILTER_DESCRIPTOR 構造体の配列へのポインターです。配列の要素数は FilterDescCount メンバーで 指定します。EVENT_FILTER_DESCRIPTOR 構造体の Type メンバーで指定される フィルターの種類ごとに、記述子は 1 つしか指定できません。
FilterDescCountDWORD4+40+32

EnableFilterDesc メンバーが指す EVENT_FILTER_DESCRIPTOR 配列の要素数 (フィルター数) です。

FilterDescCount メンバーは、EnableFilterDesc メンバーが指す配列内の EVENT_FILTER_DESCRIPTOR 構造体の数と一致している必要があります。

公式ドキュメント

ENABLE_TRACE_PARAMETERS 構造体には、 EnableTraceEx2 を使用してプロバイダーを有効にするための情報が格納されます。

解説(Remarks)

ENABLE_TRACE_PARAMETERS 構造体はバージョン 2 の構造体であり、 ENABLE_TRACE_PARAMETERS_V1 構造体に代わるものです。

Windows 8.1、Windows Server 2012 R2 以降: ロガー セッションで特定の条件に 基づいてフィルター処理を行うために、イベント ペイロード フィルター、スコープ フィルター、およびスタック ウォーク フィルターを EnableTraceEx2 関数、ならびに ENABLE_TRACE_PARAMETERS 構造体および EVENT_FILTER_DESCRIPTOR 構造体で使用できます。イベント ペイロード フィルターの詳細については、 EnableTraceEx2TdhCreatePayloadFilterTdhAggregatePayloadFilters の各関数、および EVENT_FILTER_DESCRIPTOR 構造体と PAYLOAD_FILTER_PREDICATE 構造体を参照してください。

通常、64 ビット コンピューターでは、ページ フォールトが許可されないコンテキストに おいてカーネル スタックをキャプチャできません。x64 でカーネル スタックのウォークを 有効にするには、メモリ管理のレジストリ値 DisablePagingExecutive を 1 に設定します。 DisablePagingExecutive レジストリ値は、次のレジストリ キーの下にあります。 HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Memory Management。 システムのメモリ使用量が増加するため、これは一時的な診断目的でのみ行ってください。

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

各言語での定義

#include <windows.h>

// ENABLE_TRACE_PARAMETERS  (x64 48 / x86 36 バイト)
typedef struct ENABLE_TRACE_PARAMETERS {
    DWORD Version;
    DWORD EnableProperty;
    DWORD ControlFlags;
    GUID SourceId;
    EVENT_FILTER_DESCRIPTOR* EnableFilterDesc;
    DWORD FilterDescCount;
} ENABLE_TRACE_PARAMETERS;
using System;
using System.Runtime.InteropServices;

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
public struct ENABLE_TRACE_PARAMETERS
{
    public uint Version;
    public uint EnableProperty;
    public uint ControlFlags;
    public Guid SourceId;
    public IntPtr EnableFilterDesc;
    public uint FilterDescCount;
}
Imports System.Runtime.InteropServices

<StructLayout(LayoutKind.Sequential, CharSet:=CharSet.Unicode)>
Public Structure ENABLE_TRACE_PARAMETERS
    Public Version As UInteger
    Public EnableProperty As UInteger
    Public ControlFlags As UInteger
    Public SourceId As Guid
    Public EnableFilterDesc As IntPtr
    Public FilterDescCount As UInteger
End Structure
import ctypes
from ctypes import wintypes

class ENABLE_TRACE_PARAMETERS(ctypes.Structure):
    _fields_ = [
        ("Version", wintypes.DWORD),
        ("EnableProperty", wintypes.DWORD),
        ("ControlFlags", wintypes.DWORD),
        ("SourceId", GUID),
        ("EnableFilterDesc", ctypes.c_void_p),
        ("FilterDescCount", wintypes.DWORD),
    ]
#[repr(C)]
pub struct ENABLE_TRACE_PARAMETERS {
    pub Version: u32,
    pub EnableProperty: u32,
    pub ControlFlags: u32,
    pub SourceId: GUID,
    pub EnableFilterDesc: *mut core::ffi::c_void,
    pub FilterDescCount: u32,
}
import "golang.org/x/sys/windows"

type ENABLE_TRACE_PARAMETERS struct {
	Version uint32
	EnableProperty uint32
	ControlFlags uint32
	SourceId windows.GUID
	EnableFilterDesc uintptr
	FilterDescCount uint32
}
type
  ENABLE_TRACE_PARAMETERS = record
    Version: DWORD;
    EnableProperty: DWORD;
    ControlFlags: DWORD;
    SourceId: TGUID;
    EnableFilterDesc: Pointer;
    FilterDescCount: DWORD;
  end;
const ENABLE_TRACE_PARAMETERS = extern struct {
    Version: u32,
    EnableProperty: u32,
    ControlFlags: u32,
    SourceId: GUID,
    EnableFilterDesc: ?*anyopaque,
    FilterDescCount: u32,
};
type
  ENABLE_TRACE_PARAMETERS {.bycopy.} = object
    Version: uint32
    EnableProperty: uint32
    ControlFlags: uint32
    SourceId: GUID
    EnableFilterDesc: pointer
    FilterDescCount: uint32
struct ENABLE_TRACE_PARAMETERS
{
    uint Version;
    uint EnableProperty;
    uint ControlFlags;
    GUID SourceId;
    void* EnableFilterDesc;
    uint FilterDescCount;
}

HSP用 定義

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

; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x86 レイアウト)
; ENABLE_TRACE_PARAMETERS サイズ: 36 バイト(x86)
dim st, 9    ; 4byte整数×9(構造体サイズ 36 / 4 切り上げ)
; Version : DWORD (+0, 4byte)  st.0 = 値  /  値 = st.0   (lpoke/lpeek も可)
; EnableProperty : DWORD (+4, 4byte)  st.1 = 値  /  値 = st.1   (lpoke/lpeek も可)
; ControlFlags : DWORD (+8, 4byte)  st.2 = 値  /  値 = st.2   (lpoke/lpeek も可)
; SourceId : GUID (+12, 16byte)  varptr(st)+12 を基点に操作(16byte:入れ子/配列)
; EnableFilterDesc : EVENT_FILTER_DESCRIPTOR* (+28, 4byte)  varptr(st)+28 を基点に操作(4byte:入れ子/配列)
; FilterDescCount : DWORD (+32, 4byte)  st.8 = 値  /  値 = st.8   (lpoke/lpeek も可)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。
; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x64 レイアウト)
; ENABLE_TRACE_PARAMETERS サイズ: 48 バイト(x64)
dim st, 12    ; 4byte整数×12(構造体サイズ 48 / 4 切り上げ)
; Version : DWORD (+0, 4byte)  st.0 = 値  /  値 = st.0   (lpoke/lpeek も可)
; EnableProperty : DWORD (+4, 4byte)  st.1 = 値  /  値 = st.1   (lpoke/lpeek も可)
; ControlFlags : DWORD (+8, 4byte)  st.2 = 値  /  値 = st.2   (lpoke/lpeek も可)
; SourceId : GUID (+12, 16byte)  varptr(st)+12 を基点に操作(16byte:入れ子/配列)
; EnableFilterDesc : EVENT_FILTER_DESCRIPTOR* (+32, 8byte)  varptr(st)+32 を基点に操作(8byte:入れ子/配列)
; FilterDescCount : DWORD (+40, 4byte)  st.10 = 値  /  値 = st.10   (lpoke/lpeek も可)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。
; IronHSP は NSTRUCT(構造体)をサポート。32bit/64bit どちらでも同じコードで動作します。
; ※GUID・入れ子構造体はデフォルト型でないため、依存する #defstruct を先に定義(下記に同梱)。
#defstruct global GUID, pack=1
    #field int Data1
    #field short Data2
    #field short Data3
    #field byte Data4 8
#endstruct

#defstruct global ENABLE_TRACE_PARAMETERS
    #field int Version
    #field int EnableProperty
    #field int ControlFlags
    #field GUID SourceId
    #field intptr EnableFilterDesc
    #field int FilterDescCount
#endstruct

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