在程式碼中加入追蹤記錄

本頁說明如何在 Fuchsia 元件的程式碼中加入追蹤記錄。

必要條件

開始之前,請確認已完成下列工作:

在程式碼中使用追蹤巨集

將元件註冊為追蹤提供者後, 您可以在元件的程式碼中加入追蹤記錄。

下列動作通常很實用,可以輕鬆加入程式碼 追蹤巨集:

如需所有可用的追蹤巨集清單,請參閱 追蹤:C 和 C++ 巨集

追蹤即時事件

下列範例 (針對 C 和 C++) 會寫入即時事件 代表時間中的單一時刻:

TRACE_INSTANT("helloworld", "hello_world_test", TRACE_SCOPE_PROCESS, "message", TA_STRING("Hello, World!"));

這個範例指定 helloworld 的類別、hello_world_test 的名稱, TRACE_SCOPE_PROCESS 的範圍,以及鍵和值組合

如要進一步瞭解 TRACE_INSTANT 巨集,請參閱 TRACE_INSTANT

停用追蹤

在某些情況下,您可能會想完全停用追蹤功能 (例如: 例如當您準備將元件發布至實際工作環境時)。 如果程式碼中加入 NTRACE 巨集,追蹤巨集就不會 任何程式碼

以下範例 (針對 C 和 C++) 顯示 NTRACE 巨集:

#define NTRACE  // disable tracing
#include <lib/trace/event.h>

請務必定義 #include 陳述式之前的 NTRACE 巨集。

在以下範例中,rx_counttx_count 欄位僅供 所以如果宣告 NTRACE 表示追蹤記錄已停用 欄位不會佔用 my_statistics_t 結構中的空間。

typedef struct {
#ifndef NTRACE  // reads as "if tracing is not disabled"
    uint64_t    rx_count;
    uint64_t    tx_count;
#endif
    uint64_t    npackets;
} my_statistics_t;

但如果您需要有條件地編譯程式碼,才能管理 統計資料的記錄,您可以使用 TRACE_INSTANT 巨集:

#ifndef NTRACE
    status.tx_count++;
    TRACE_INSTANT("bandwidth", "txpackets", TRACE_SCOPE_PROCESS,
                  "count", TA_UINT64(status.tx_count));
#endif  // NTRACE

如要進一步瞭解 NTRACE 巨集,請參閱 NTRACE

判斷追蹤功能是否已開啟

在某些情況下,您可能需要決定是否要在執行階段開啟追蹤功能。 如果因為 NTRACE 未定義而在程式碼中編譯追蹤, TRACE_ENABLED() 巨集會決定是否追蹤記錄追蹤記錄 供應商已開啟。如果編譯追蹤記錄,TRACE_ENABLED() 一律會 會傳回 false。

#ifndef NTRACE
    if (TRACE_ENABLED()) {
        int v = do_something_expensive();
        TRACE_INSTANT(...
    }
#endif  // NTRACE

上述範例 (適用於 C 和 C++) 同時使用 #ifndefTRACE_ENABLED() 巨集,因為這個函式 do_something_expensive() 可能不存在於停用追蹤記錄的版本 程式碼。

如要進一步瞭解 TRACE_ENABLED 巨集,請參閱 TRACE_ENABLED

設定事件時間

如需計算函式或程序的時間,請參閱下方範例 (適用於 C++) 從 blobfs vnode 建構函式建立:

zx_status_t VnodeBlob::InitCompressed() {
    TRACE_DURATION("blobfs", "Blobfs::InitCompressed", "size", inode_.blob_size,
                   "blocks", inode_.num_blocks);
    ...

這個範例會記錄建構函式中花費的時間 以及區塊大小和區塊數量這是 C++ 範例 編譯器可以推斷資料類型。

如要進一步瞭解 TRACE_DURATION 巨集,請參閱 TRACE_DURATION

在元件中加入追蹤程式碼後,您就可以開始收集 從元件擷取追蹤記錄如需詳細資訊,請參閱 錄製追蹤記錄並以視覺化方式呈現頁面。