Add tracing in your code

This page describes how to add tracing to your Fuchsia component's code.

Prerequisites

Before you begin, make sure you have completed the following tasks:

Also, make sure to use the relevant library in your code:

C

Note: The header file is defined in//zircon/system/ulib/trace/include/lib/trace/internal/event_common.h.SeeTracing: C and C++ macros for the referencepage.
#include <lib/trace/event.h>

C++

Note: The header file is defined in/zircon/system/ulib/trace/include/lib/trace/internal/event_common.h.SeeTracing: C and C++ macros for the referencepage.
#include <lib/trace/event.h>

Rust

Note: See therustdoc page for thefuchsia_tracecrate reference page.
usefuchsia_trace::{ArgValue,Scope,...};

Use tracing macros in your code

Once your component is registered as atrace provider,you can add tracing in your component's code.

The following actions are often useful and can easily be added in the codeusing the tracing macros:

For the list of all available tracing macros, see

Trace an instant event

The following example writes an instant event representing a single moment in time:

Rust

fuchsia_trace::instant!(c"helloworld",c"hello_world_test",fuchsia_trace::Scope::Process,"message"=>"Hello, World!");

This example specifies a category ofhelloworld, a name ofhello_world_test,a scope ofTRACE_SCOPE_PROCESS, and a key and value pair.

For more information on theinstant! macro, seeinstant!.

C++

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

This example specifies a category ofhelloworld, a name ofhello_world_test,a scope ofTRACE_SCOPE_PROCESS, and a key and value pair.

For more information on theTRACE_INSTANT macro, seeTRACE_INSTANT.

C

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

This example specifies a category ofhelloworld, a name ofhello_world_test,a scope ofTRACE_SCOPE_PROCESS, and a key and value pair.

For more information on theTRACE_INSTANT macro, seeTRACE_INSTANT.

Time an event

This example shows you how to time a function or procedure:

Note: This example is based on a ablobfs vnode constructor.

Rust

fnInitCompressed(){fuchsia_trace::duration!(c"helloworld",c"hello_world_test",fuchsia_trace::Scope::Process,"message"=>"Hello, World!");...// Duration ends due to RAII}

This example records the length of time spent in the constructor,along with the size and number of blocks.

For more information on theduration! macro, seeduration!.

C++

zx_status_tVnodeBlob::InitCompressed(){TRACE_DURATION("blobfs","Blobfs::InitCompressed","size",inode_.blob_size,"blocks",inode_.num_blocks);...// Duration ends due to RAII}

This example records the length of time spent in the constructor,along with the size and number of blocks. Since this is a C++ example,the compiler can infer the data types.

For more information on theTRACE_DURATION macro, seeTRACE_DURATION.

C

zx_status_tVnodeBlob_InitCompressed(inode_tinode){TRACE_DURATION_BEGIN("blobfs","Blobfs_InitCompressed","size",inode.blob_size,"blocks",inode.num_blocks);...TRACE_DURATION_END("blobfs","Blobfs_InitCompressed");}

This example records the length of time spent in the constructor,along with the size and number of blocks.

For more information on theTRACE_DURATION_BEGIN andTRACE_DURATION_END macros, seeTRACE_DURATION_BEGIN andTRACE_DURATION_END.

Disable tracing

There are cases where you may wish to entirely disable tracing (forinstance, when you are about to release the component into production).If theNTRACE macro is added in your code, the tracing macros do notgenerate any code.

The following example (for C and C++) shows theNTRACE macro:

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

Make sure that you define theNTRACE macro before the#includestatement.

In the example below, therx_count andtx_count fields are used only withtracing, so ifNTRACE is asserted, which indicates that tracing is disabled,the fields do not take up space in themy_statistics_t structure.

typedefstruct{#ifndef NTRACE// reads as "if tracing is not disabled"uint64_trx_count;uint64_ttx_count;#endifuint64_tnpackets;}my_statistics_t;

However, if you do need to conditionally compile the code for managingthe recording of the statistics, you can use theTRACE_INSTANT macro:

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

For more information on theNTRACE macro, seeNTRACE.

Determine if tracing is on

In some cases, you may need to determine if tracing is on at runtime.

Rust

iffuchsia_trace::is_enabled(){letv=do_something_expensive();fuchsia_trace::instant!(...}

The rust trace bindings don't support compile time checking if tracing is disabled.However, if tracing is disabled at compile time, checkingis_enabled isnot performance intensive.

For more information onis_enabled, seeis_enabled.

C++

If tracing is compiled in your code becauseNTRACE is not defined,theTRACE_ENABLED() macro determines if tracing for your traceprovider is on. If tracing is compiled out,TRACE_ENABLED() alwaysreturns false.

#ifndef NTRACEif(TRACE_ENABLED()){intv=do_something_expensive();TRACE_INSTANT(...}#endif// NTRACE

The example above uses both the#ifndef and theTRACE_ENABLED() macro together because the functiondo_something_expensive() may not exist in the trace-disabled versionof your code.

For more information on theTRACE_ENABLED macro, seeTRACE_ENABLED.

C

If tracing is compiled in your code becauseNTRACE is not defined,theTRACE_ENABLED() macro determines if tracing for your traceprovider is on. If tracing is compiled out,TRACE_ENABLED() alwaysreturns false.

#ifndef NTRACEif(TRACE_ENABLED()){intv=do_something_expensive();TRACE_INSTANT(...}#endif// NTRACE

The example above uses both the#ifndef and theTRACE_ENABLED() macro together because the functiondo_something_expensive() may not exist in the trace-disabled versionof your code.

For more information on theTRACE_ENABLED macro, seeTRACE_ENABLED.

Once you have added tracing code to your component, you can now collect atrace from the component. For more information, see the nextRecord and visualize a trace page.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-03-22 UTC.