StartTraceA 函式 (evntrace.h)

  • 發行項

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

重要

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

語法

ULONG WMIAPI StartTraceA(
  [out]     PTRACEHANDLE            TraceHandle,
  [in]      LPCSTR                  InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties
);

參數

[out] TraceHandle

接收事件追蹤會話的控制碼，以便後續搭配 ControlTrace等 API 使用。

如果函式失敗，請勿使用此控制碼。 請勿比較會話控制碼與INVALID_HANDLE_VALUE。 如果控制碼無效，會話控制碼為 0。

[in] InstanceName

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

重要

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

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

[in, out] Properties

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

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

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

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

傳回值

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

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

  • ERROR_BAD_LENGTH

    以下其中一項為正確：

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

  • ERROR_INVALID_PARAMETER

    以下其中一項為正確：

    • 屬性 為 Null。
    • TraceHandle 為 Null。
    • Properties的LogFileNameOffset成員無效。
    • Properties的LoggerNameOffset成員無效。
    • Properties的LogFileMode成員會指定不正確旗標組合。
    • Wnode.Guid成員是SystemTraceControlGuid，但InstanceName參數不會KERNEL_LOGGER_NAME。

  • ERROR_ALREADY_EXISTS

    具有相同名稱或 GUID 的會話已在執行中。

  • ERROR_BAD_PATHNAME

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

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

  • 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。

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

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

系統記錄器

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

  • Properties成員LogFileMode包含慣用的 EVENT_TRACE_SYSTEM_LOGGER_MODE旗標 (慣用) 。
  • Properties成員Wnode.Guid設定為SystemTraceControlGuid或GlobalLoggerGuid (已被取代 - 不應該用於新程式碼，因為它會與其他也嘗試使用這些 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，並將Properties的Wnode.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