共用方式為


StartTraceA 函式 (evntrace.h)

StartTrace 函式會註冊並啟動事件追蹤會話。

重要

跨進程事件追蹤會話是有限的系統資源。 開發人員應該避免在客戶計算機上啟動事件追蹤會話。 當需要事件追蹤會話時,它們應該限制為最小的可能範圍:盡可能使用最少的會話、盡可能使用僅限進程會話,如果可能的話, (EVENT_TRACE_PRIVATE_LOGGER_MODE | EVENT_TRACE_PRIVATE_IN_PROC) ,只有在案例需要收集時啟動追蹤,只要完成案例,請立即停止追蹤,限制會話所使用的記憶體數量, 並使用 strict 事件篩選條件,因此您不會收集不必要的事件。

語法

ULONG WMIAPI StartTraceA(
            CONTROLTRACE_ID         *TraceId,
  [in]      LPCSTR                  InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties
);

參數

TraceId

[in] InstanceName

包含事件追蹤會話名稱的 Null 終止字串。 會話名稱限制為 1,024 個字元,不區分大小寫,而且必須是唯一的。

重要

使用會話的描述性名稱,以便從會話名稱判斷會話的擁有權和使用方式。 請勿使用 GUID 或其他不具決定性或非描述性值。 請勿附加隨機數位,讓您的會話名稱是唯一的。 ETW 會話是有限的資源,因此您的元件不應該啟動多個會話。 如果您的元件會話已在元件啟動時執行,您的元件應該清除孤立的會話,而不是建立第二個會話。

此函式會將您提供的會話名稱複製到 PropertiesLoggerNameOffset 成員所指向的位移。

[in, out] Properties

指定會話行為的 EVENT_TRACE_PROPERTIES 結構的指標。 以下是要設定之 結構的重要成員:

  • Wnode.BufferSize
  • Wnode.Guid
  • Wnode.ClientContext
  • Wnode.Flags
  • LogFileMode
  • LogFileNameOffset
  • LoggerNameOffset

根據您選擇的記錄檔類型,您可能也需要指定 MaximumFileSize 的值。 如需設定 Properties 參數和會話行為的詳細資訊,請參閱一節。

從 Windows 10 版本 1703 開始: 為了提升跨進程案例的效能,您現在可以在啟動整個系統的私人記錄器時傳入 StartTrace 篩選。 您必須傳入新的 EVENT_TRACE_PROPERTIES_V2 結構,才能包含篩選資訊。 如需詳細資訊 ,請參閱設定和啟動私人記錄器會話

傳回值

如果函式成功,傳回值會ERROR_SUCCESS。

如果函式失敗,傳回值就是其中一個 系統錯誤碼。 以下是一些常見的錯誤及其原因。

  • ERROR_BAD_LENGTH

    以下其中一項為正確:

    • PropertiesWnode.BufferSize 成員會指定不正確的大小。
    • 屬性 沒有足夠的空間配置來保存 InstanceName 的複本。
  • ERROR_INVALID_PARAMETER

    以下其中一項為正確:

    • 屬性NULL
    • TraceHandleNULL
    • PropertiesLogFileNameOffset 成員無效。
    • PropertiesLoggerNameOffset 成員無效。
    • PropertiesLogFileMode 成員會指定無效的旗標組合。
    • Wnode.Guid 成員是 SystemTraceControlGuid,但 InstanceName 參數不會KERNEL_LOGGER_NAME
  • ERROR_ALREADY_EXISTS

    具有相同名稱或 GUID 的工作階段已在執行中。

  • ERROR_BAD_PATHNAME

    基於下列其中一個原因,您可以收到此錯誤:

    • 另一個會話已經使用 Properties 結構的 LogFileNameOffset 成員所指定的檔名。
    • LogFileModeLogFileNameOffset 都是零。
  • ERROR_DISK_FULL

    磁碟驅動器上沒有足夠的可用空間可供記錄檔使用。 如果:

    • MaximumFileSize 不是零的,而且記錄檔沒有 可用的 MaximumFileSize 位元組
    • 磁碟驅動器是系統磁碟驅動器,而且沒有額外的 200 MB 可用
    • MaximumFileSize 為零,而且沒有額外的 200 MB 可用

    選擇具有更多空間的磁碟驅動器,或使用) 時,請減少 MaximumFileSize (中指定的大小。

  • ERROR_ACCESS_DENIED

    只有具有系統管理許可權、效能記錄使用者群組中的使用者,以及以LocalSystem、LocalService、NetworkService 執行的服務,才能控制事件追蹤會話。 若要授與受限制的使用者控制追蹤會話的能力,請將它們新增至 [效能記錄使用者] 群組。 只有具有以 LocalSystem 身分執行之系統管理許可權和服務的使用者,才能控制 NT 核心記錄器會話。

    如果使用者是效能記錄使用者群組的成員,他們可能沒有許可權在指定的資料夾中建立記錄檔。

  • ERROR_NO_SYSTEM_RESOURCES

    以下其中一項為正確:

    • 記錄會話會使用 EVENT_TRACE_SYSTEM_LOGGER_MODE 旗標,而且已達到系統記錄器數目上限, (8) 。

    • 已達到系統上的記錄會話數目上限。 在記錄會話停止之前,無法建立新的記錄器。 在大部分系統上,記錄會話數目上限為 64。

      您可以藉由在 編輯 REG_DWORD 索引鍵 HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\WMI@EtwMaxLoggers,來變更系統記錄會話數目上限。 允許的值是 32 到 256,包含。 需要重新啟動,任何變更才會生效。

      請注意,記錄器會使用系統資源。 如果這些位置已填滿,增加系統上的記錄器數目將會產生效能成本。 此限制存在,以防止過度使用系統資源。

      重要

      只有系統管理員才能手動調整限制,才能啟用特定案例。 程式或驅動程式不得自動修改 EtwMaxLoggers 設定。

      在 Windows 10 版本 1709 之前,這是非私人記錄器 64 個記錄器的固定上限。

備註

事件追蹤控制器會呼叫此函式。

會話會保持作用中,直到會話停止、計算機重新啟動、發生 I/O 錯誤,或達到非循環記錄的檔案大小上限。 若要停止事件追蹤會話,請呼叫 ControlTrace 函式,並將 ControlCode 參數設定為 EVENT_TRACE_CONTROL_STOP

您無法使用與) 指定的 Properties.Wnode.Guid 相同會話 GUID (來啟動多個作業階段。 在大部分情況下,您將設定 Properties.Wnode.Guid 為全部零 (,也就是 GUID_NULL) ,以允許 ETW 系統為會話產生新的 GUID。

若要指定私人記錄器會話,請將 PropertiesWnode.Guid 成員設定為提供者的控件 GUID,而不是私人記錄器會話的控件 GUID。 提供者必須先註冊 GUID,才能呼叫 StartTrace

您不使用此函式來啟動全域記錄器會話, (已被取代) 。 如需啟動全域記錄器會話的詳細資訊,請參閱 設定和啟動全域記錄器會話

系統記錄器

若要讓記錄器成為系統記錄器,並從 SystemTraceProvider 或其他 系統提供者接收事件,下列任何一項都必須成立:

  • Properties 成員LogFileMode包含慣用 ) (EVENT_TRACE_SYSTEM_LOGGER_MODE 旗標。
  • Properties 成員 Wnode.Guid 設定為 SystemTraceControlGuidGlobalLoggerGuid (已被取代 - 不應該用於新的程式碼,因為它會與其他也嘗試使用這些 GUID 的元件衝突) 。
  • InstanceName 設定為 KERNEL_LOGGER_NAME (已被取代, 不應該用於新的程式碼,因為它會與其他嘗試使用此名稱的元件衝突) 。

注意

 系統記錄器必須設定EVENT_TRACE_PROPERTIES結構的 EnableFlags 成員,以指出追蹤中應該包含哪些 SystemTraceProvider 事件。

因為系統記錄器會收到特殊的核心事件,所以會受到其他限制:

  • 同一個系統上不能有超過8個使用中的系統記錄器。
  • 無法在 Windows Server 容器內建立系統記錄器。
  • 系統記錄器無法使用 EVENT_TRACE_USE_PAGED_MEMORY 旗標。
  • 在 Windows 10 版本 1703 之前,任何系統記錄器都不能同時使用 2 個不同的時鐘類型。 例如,如果一個作用中的系統記錄器使用「CPU 週期計數器」時鐘類型,而另一個使用中系統記錄器使用「查詢性能計數器」時鐘類型,則任何使用「系統時間」時鐘類型的系統記錄器嘗試啟動系統記錄器都會失敗,因為它需要啟用第三個時鐘類型。 由於這項限制,Microsoft 強烈建議系統記錄器不使用「系統時間」時鐘類型。
  • 從 Windows 10 版本 1703 開始,已移除時鐘類型限制。 系統記錄器現在可以同時使用這三種時鐘類型。

若要指定 NT 核心記錄器會話 (已被取代) ,請將 InstanceName 設定為 KERNEL_LOGGER_NAME,並將 PropertiesWnode.Guid 成員設定為 SystemTraceControlGuid。 如果您未將 GUID 指定為 SystemTraceControlGuid,ETW 會覆寫 GUID 值,並將其設定為 SystemTraceControlGuid

範例

如需使用 StartTrace 的範例,請參閱 設定和啟動事件追蹤會話

注意

evntrace.h 標頭會將 StartTrace 定義為別名,根據 UNICODE 預處理器常數的定義,自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼,可能會導致編譯或運行時間錯誤不符。 如需詳細資訊,請參閱 函式原型的慣例

規格需求

需求
最低支援的用戶端 Windows Vista [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2008 [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 evntrace.h
程式庫 Windows 8.1 和 Windows Server 2012 R2 上的 Sechost.lib;Windows 8、Windows Server 2012、Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista 上的 Advapi32.lib
Dll windows 8.1 和 Windows Server 2012 R2 上的 Sechost.dll;Windows 8、Windows Server 2012、Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista 上的 Advapi32.dll

另請參閱

ControlTrace

EVENT_TRACE_PROPERTIES