ホーム › System.Diagnostics.Etw › EnableTrace

EnableTrace

関数

トレースセッションに対してイベントプロバイダーを有効または無効にする。

DLLADVAPI32.dll呼出規約winapi対応OSWindows 2000 以降

シグネチャ

// ADVAPI32.dll
#include <windows.h>

WIN32_ERROR EnableTrace(
    DWORD Enable,
    DWORD EnableFlag,
    DWORD EnableLevel,
    const GUID* ControlGuid,
    ULONGLONG TraceId
);

パラメーター

名前型方向説明

Enable DWORD in プロバイダーからのイベント受信を有効にする場合、またはプロバイダーからイベントを受信する際に使用する設定を調整する場合(レベルやキーワードの変更など)は 1 を設定します。プロバイダーからのイベント受信を無効にする場合は 0 を設定します。

EnableFlag

DWORD

プロバイダーに書き込ませたいイベントのカテゴリを決定するキーワードの 32 ビットビットマスクです。プロバイダーは通常、EnableLevel の条件を満たすことに加えて、イベントのキーワードビットがこの値に設定されたビットのいずれかに一致する場合、またはイベントにキーワードビットが設定されていない場合に、そのイベントを書き込みます。

メモ

EventRegister ベースのプロバイダーは 64 ビットのキーワードをサポートします。64 ビットの MatchAnyKeyword マスクを使用してプロバイダーを有効にするには、EnableTraceEx2 を使用してください。

EnableLevel

DWORD

プロバイダーに書き込ませたいイベントの最大レベルを示す値です。プロバイダーは通常、EnableFlag の条件を満たすことに加えて、イベントのレベルがこの値以下である場合に、そのイベントを書き込みます。

この値は 1 から 255 の範囲である必要があります。Microsoft はレベル 1〜5 のセマンティクスを以下のように定義しています。値が小さいほど深刻なイベントを示します。EnableLevel の各値は、指定したレベルおよびそれよりも深刻なすべてのレベルを有効にします。たとえば TRACE_LEVEL_WARNING を指定すると、コンシューマーは警告、エラー、および重大なイベントを受信します。

値	意味
TRACE_LEVEL_CRITICAL (1)	異常終了またはターミネーションのイベント
TRACE_LEVEL_ERROR (2)	深刻なエラーイベント
TRACE_LEVEL_WARNING (3)	割り当て失敗などの警告イベント
TRACE_LEVEL_INFORMATION (4)	エラーではない情報イベント
TRACE_LEVEL_VERBOSE (5)	詳細な診断イベント

TRACE_LEVEL 定数は evntrace.h で定義されています。同等の WINMETA_LEVEL 定数は winmeta.h で定義されています。

ControlGuid GUID* in 有効または無効にするイベントプロバイダーのコントロール GUID(プロバイダー ID)です。

TraceId ULONGLONG in イベントを受け取るトレースセッションのハンドル。

戻り値の型: WIN32_ERROR

公式ドキュメント

トレースセッションコントローラーは、ETW イベントの構成方法を設定するために EnableTrace を呼び出します。

戻り値

関数が成功した場合、戻り値は ERROR_SUCCESS です。

関数が失敗した場合、戻り値はシステムエラーコードのいずれかです。以下に、一般的なエラーとその原因をいくつか示します。

ERROR_INVALID_PARAMETER

次のいずれかに該当します。
- ControlGuid が NULL である。
- TraceHandle が NULL である。
ERROR_INVALID_FUNCTION

プロバイダーが登録されていない場合、有効化フラグおよびレベルを変更することはできません。
ERROR_WMI_GUID_NOT_FOUND

プロバイダーが登録されていません。KB307331 または Windows 2000 Service Pack 4 がインストールされており、かつプロバイダーが登録されていない場合に発生します。このエラーを回避するには、まずプロバイダーを登録する必要があります。
ERROR_NO_SYSTEM_RESOURCES

プロバイダーを有効にできるトレースセッションの数を超過しました。
ERROR_ACCESS_DENIED

管理者権限を持つユーザー、Performance Log Users グループに属するユーザー、および LocalSystem、LocalService、NetworkService として実行されているサービスのみが、プロセス間セッションに対してイベントプロバイダーを有効にできます。制限付きユーザーにイベントプロバイダーを有効にする権限を付与するには、そのユーザーを Performance Log Users グループに追加するか、EventAccessControl を参照してください。

Windows XP および Windows 2000: 誰でもイベントプロバイダーを有効にできます。

解説(Remarks)

イベントトレースコントローラーは、セッションにイベントを書き込むイベントプロバイダーを構成するためにこの関数を呼び出します。たとえば、コントローラーはプロバイダーからのイベント収集を開始するため、プロバイダーから収集するイベントのレベルやキーワードを調整するため、またはプロバイダーからのイベント収集を停止するために、この関数を呼び出すことがあります。

この関数は廃止されました。追加機能を利用するには、新しいコードでは EnableTraceEx2 を使用してください。

次の 2 つの関数呼び出しは同等です。

// 廃止:
Status = EnableTrace(
    Enable,
    EnableFlag,
    EnableLevel,
    ControlGuid,
    TraceHandle);

// 更新された同等のコード:
Status = EnableTraceEx2(
    TraceHandle,
    ControlGuid,
    Enable,      // ControlCode
    EnableLevel,
    EnableFlag,  // MatchAnyKeyword
    0,           // MatchAllKeyword
    0,           // Timeout
    NULL);       // EnableParameters

セッション向けにプロバイダーを構成する際のセマンティクスの詳細については、EnableTraceEx2 のドキュメントを参照してください。

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

各言語での呼び出し定義

// ADVAPI32.dll
#include <windows.h>

WIN32_ERROR EnableTrace(
    DWORD Enable,
    DWORD EnableFlag,
    DWORD EnableLevel,
    const GUID* ControlGuid,
    ULONGLONG TraceId
);

[DllImport("ADVAPI32.dll", ExactSpelling = true)]
static extern uint EnableTrace(
    uint Enable,   // DWORD
    uint EnableFlag,   // DWORD
    uint EnableLevel,   // DWORD
    ref Guid ControlGuid,   // GUID*
    ulong TraceId   // ULONGLONG
);

<DllImport("ADVAPI32.dll", ExactSpelling:=True)>
Public Shared Function EnableTrace(
    Enable As UInteger,   ' DWORD
    EnableFlag As UInteger,   ' DWORD
    EnableLevel As UInteger,   ' DWORD
    ByRef ControlGuid As Guid,   ' GUID*
    TraceId As ULong   ' ULONGLONG
) As UInteger
End Function

' Enable : DWORD
' EnableFlag : DWORD
' EnableLevel : DWORD
' ControlGuid : GUID*
' TraceId : ULONGLONG
Declare PtrSafe Function EnableTrace Lib "advapi32" ( _
    ByVal Enable As Long, _
    ByVal EnableFlag As Long, _
    ByVal EnableLevel As Long, _
    ByVal ControlGuid As LongPtr, _
    ByVal TraceId As LongLong) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

EnableTrace = ctypes.windll.advapi32.EnableTrace
EnableTrace.restype = wintypes.DWORD
EnableTrace.argtypes = [
    wintypes.DWORD,  # Enable : DWORD
    wintypes.DWORD,  # EnableFlag : DWORD
    wintypes.DWORD,  # EnableLevel : DWORD
    ctypes.c_void_p,  # ControlGuid : GUID*
    ctypes.c_ulonglong,  # TraceId : ULONGLONG
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ADVAPI32.dll')
EnableTrace = Fiddle::Function.new(
  lib['EnableTrace'],
  [
    -Fiddle::TYPE_INT,  # Enable : DWORD
    -Fiddle::TYPE_INT,  # EnableFlag : DWORD
    -Fiddle::TYPE_INT,  # EnableLevel : DWORD
    Fiddle::TYPE_VOIDP,  # ControlGuid : GUID*
    -Fiddle::TYPE_LONG_LONG,  # TraceId : ULONGLONG
  ],
  -Fiddle::TYPE_INT)

#[link(name = "advapi32")]
extern "system" {
    fn EnableTrace(
        Enable: u32,  // DWORD
        EnableFlag: u32,  // DWORD
        EnableLevel: u32,  // DWORD
        ControlGuid: *const GUID,  // GUID*
        TraceId: u64  // ULONGLONG
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("ADVAPI32.dll")]
public static extern uint EnableTrace(uint Enable, uint EnableFlag, uint EnableLevel, ref Guid ControlGuid, ulong TraceId);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ADVAPI32_EnableTrace' -Namespace Win32 -PassThru
# $api::EnableTrace(Enable, EnableFlag, EnableLevel, ControlGuid, TraceId)

#uselib "ADVAPI32.dll"
#func global EnableTrace "EnableTrace" sptr, sptr, sptr, sptr, sptr
; EnableTrace Enable, EnableFlag, EnableLevel, varptr(ControlGuid), TraceId   ; 戻り値は stat
; Enable : DWORD -> "sptr"
; EnableFlag : DWORD -> "sptr"
; EnableLevel : DWORD -> "sptr"
; ControlGuid : GUID* -> "sptr"
; TraceId : ULONGLONG -> "sptr"
; ※HSP3.7は int64 引数(64bit値渡し)に非対応です。
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "ADVAPI32.dll"
#cfunc global EnableTrace "EnableTrace" int, int, int, var, int64
; res = EnableTrace(Enable, EnableFlag, EnableLevel, ControlGuid, TraceId)
; Enable : DWORD -> "int"
; EnableFlag : DWORD -> "int"
; EnableLevel : DWORD -> "int"
; ControlGuid : GUID* -> "var"
; TraceId : ULONGLONG -> "int64"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。
; ※int64 引数の DLL 値渡しは x64 ランタイム(hsp3_64)のみ対応(x86 は未対応)。#uselib "ADVAPI32.dll"
#cfunc global EnableTrace "EnableTrace" int, int, int, sptr, int64
; res = EnableTrace(Enable, EnableFlag, EnableLevel, varptr(ControlGuid), TraceId)
; Enable : DWORD -> "int"
; EnableFlag : DWORD -> "int"
; EnableLevel : DWORD -> "int"
; ControlGuid : GUID* -> "sptr"
; TraceId : ULONGLONG -> "int64"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※int64 引数の DLL 値渡しは x64 ランタイム(hsp3_64)のみ対応(x86 は未対応)。