TraceLoggingWriteActivity 宏 (traceloggingprovider.h)

發行項
08/26/2023

發出具有指定活動識別碼的 TraceLogging 事件。

語法

void TraceLoggingWriteActivity(
  [in]            hProvider,
  [in]            eventName,
  [in, optional]  pActivityId,
  [in, optional]  pRelatedActivityId,
  [in, optional]  __VA_ARGS__
);

參數

[in] hProvider

要用於寫入事件的 TraceLogging 提供者控制碼。

[in] eventName

用來識別事件的簡短和唯一名稱。這必須是字串常值，而不是變數。它不能有任何內嵌 '\0' 字元。

[in, optional] pActivityId

事件的活動識別碼，或使用預設值的 Null。

[in, optional] pRelatedActivityId

事件的相關活動識別碼，或沒有相關活動識別碼的 Null。

[in, optional] __VA_ARGS__

最多 99 個額外的參數，可設定或新增欄位至事件。每個參數都必須是TraceLogging 包裝函式宏的其中一個，例如TraceLoggingLevel、TraceLoggingKeyword或TraceLoggingValue。

重要

ProviderId、Level 和 Keyword 是篩選事件的主要方法。其他種類的篩選是可行的，但額外負荷較高。一律將非零層級和關鍵字指派給每個事件。

傳回值

無

備註

TraceLoggingWriteActivity宏的每個調用都會展開至透過指定的提供者控制碼將事件寫入 ETW 所需的程式碼。

TraceLoggingWriteActivity 會檢查指定的提供者是否已註冊。如果未註冊提供者， TraceLoggingWriteActivity 不會執行任何動作。
TraceLoggingWriteActivity 會檢查是否有任何取用者正在接聽事件，就像呼叫 TraceLoggingProviderEnabled一樣。如果沒有取用者正在接聽事件， TraceLoggingWriteActivity 不會執行任何動作。
否則， TraceLoggingWriteActivity 會評估引數中指定的運行時程表達式、儲存結果、將必要的資料封裝到事件中，並呼叫 EventWriteTransfer 將事件傳送至 ETW。

產生的事件會建構如下：

事件的提供者識別碼、提供者名稱和提供者群組將來自 hProvider 參數。
事件的名稱會來自 eventName 參數。
事件的活動識別碼會來自 pActivityId 參數。如果 pActivityId 為 Null，則使用者模式事件會使用執行緒的隱含活動識別碼，而核心模式事件將使用GUID_Null。
事件的相關活動識別碼會來自 pRelatedActivityId 參數。如果 pRelatedActivityId 為 Null，事件將不會有相關的活動識別碼。
事件的層級會來自 TraceLoggingLevel 引數。如果沒有 TraceLoggingLevel 引數存在，事件的層級將會是 5 (WINEVENT_LEVEL_VERBOSE) 。如果有一個以上的 TraceLoggingLevel 引數存在，則會使用最後一個引數。若要啟用有效的事件篩選，請一律為每個事件指派有意義的非零層級。
事件的關鍵字會來自 TraceLoggingKeyword 引數。如果沒有 TraceLoggingKeyword 引數存在，事件的關鍵字將會是 0 (NONE) 。如果有一個以上的 TraceLoggingKeyword 引數存在，這些值會一起進行 OR 處理。若要啟用有效的事件篩選，請一律為每個事件指派有意義的非零關鍵字。
其他事件屬性可由 TraceLoggingOpcode、 TraceLoggingDescription、 TraceLoggingEventTag或 TraceLoggingChannel等引數來設定。
您可以使用 TraceLoggingStruct來分組事件欄位。
事件欄位是由 TraceLoggingValue、TraceLoggingInt32、TraceLoggingHResult、TraceLoggingString 等欄位引數新增。如需詳細資訊，請參閱 TraceLogging 包裝函式宏。

例如：

TraceLoggingWriteActivity(
    g_hProvider,
    "MyEvent1",
    &myActivityGuid,
    NULL, // no related activity ID
    TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
    TraceLoggingKeyword(MyNetworkingKeyword), // Provider-defined categories
    TraceLoggingHResult(hr, "NetStatus")); // Adds a "NetStatus" field.

的叫用 TraceLoggingWriteActivity(hProvider, "EventName", aid, rid, args...) 可視為擴充至程式碼，如下所示：

if (TraceLoggingProviderEnabled(hProvider, eventLevel, eventKeyword))
{
    static const metadata = { GetMetadataFromArgs(args...) };
    EVENT_DATA_DESCRIPTOR data[N] = { GetDataFromArgs(args...) };
    EventWriteTransfer(etwHandle, metadata.desc, aid, rid, N, data);
}

注意

每個 TraceLoggingWriteActivity 宏會自動檢查 TraceLoggingProviderEnabled ，因此只有在取用者接聽來自提供者的事件時，才會寫入事件。因此，通常不需要直接呼叫 TraceLoggingProviderEnabled。只有在啟用事件時，才會評估中的任何 args... 運行時程表達式。運行時程表達式將不會多次評估。

如果產生複雜的事件，您可能會收到編譯器錯誤，指出該行太長，或編譯器不在堆積空間中。當 TraceLoggingWriteActivity 宏展開至比編譯器可支援的長一行時，就會發生這種情況。如果發生這種情況，您必須簡化您的事件。

TraceLoggingWriteActivity宏會使用EVENT_DATA_DESCRIPTOR陣列將資料傳送至 ETW。 ETW 所接受的描述項數目上限為 128。由於每個參數可能需要使用 0、1 或 2 個描述元，因此在達到引數限制 (99) 之前，可以達到資料描述元限制 (128) 。

重要

請嘗試避免大型事件。 ETW 主要是針對處理小型事件而設計。 TraceLoggingWriteActivity 會以無訊息方式卸載任何太大的事件。事件的大小是根據 ETW 執行時間 () 、中繼資料 (，例如提供者名稱、事件名稱、功能變數名稱、功能變數名稱、欄位類型) 和資料 (域值) 新增的事件標頭總數。如果事件的總大小大於 65535，或取用者會話使用小於事件大小的緩衝區大小，則不會記錄事件。

對 TraceLoggingWrite 的呼叫與呼叫 TraceLoggingWriteActivity 與 pActivityId 和 pRelatedActivityId 參數的 Null 相同。如果您需要指定事件的活動識別碼，請使用 TraceLoggingWriteActivity 。

如需ActivityId和RelatedActivityId參數語意的相關資訊，請參閱EventWriteTransfer。

如需在 ETW 中撰寫活動的相關資訊，請參閱 EventActivityIdControl 。

如需協助管理 TraceLogging ETW 活動的 C++ 類別，請參閱 TraceLoggingActivity 。

規格需求


最低支援的用戶端	Windows Vista [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2008 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	traceloggingprovider.h
程式庫	Advapi32.lib