本页介绍了如何向 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_count 和 tx_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++）结合使用了 #ifndef 和 TRACE_ENABLED() 宏，因为停用跟踪记录的代码版本中可能不存在 do_something_expensive() 函数。
如需详细了解 TRACE_ENABLED 宏，请参阅 TRACE_ENABLED。
为事件设置时间
如果您需要为函数或过程计时，请参阅 blobfs vnode 构造函数中的以下示例（适用于 C++）：
zx_status_t VnodeBlob::InitCompressed() {
TRACE_DURATION("blobfs", "Blobfs::InitCompressed", "size", inode_.blob_size,
"blocks", inode_.num_blocks);
...
此示例记录了在构造函数中花费的时间长度，以及块的大小和数量。由于这是一个 C++ 示例，因此编译器可以推断数据类型。
如需详细了解 TRACE_DURATION 宏，请参阅 TRACE_DURATION。
向组件添加跟踪代码后，您现在可以从组件收集跟踪记录。如需了解详情，请参阅下一个记录并直观呈现跟踪记录页面。