Recording a trace

This document describes how to record a trace with Fuchsia's tracing system.

Prerequisites

Before you attempt to record a trace, make sure you have done the following:

  • Registered your component as a trace provider. See Registering a trace provider.
  • Added tracing in your code. See Adding tracing in your code.
  • Included the tools to your Fuchsia build. The core product and most other products include tools by default. If your build configuration does not include tools bundle by default, then you can manually add it with fx set:

    fx set PRODUCT.BOARD --with-base '//bundles:tools'
    

Use the utilities

Traces are recorded with the trace utility on a Fuchsia target. The fx traceutil command, which you can run from your development host, calls the trace utility on your Fuchsia target.

You can record a trace from your Fuchsia target from your development host or directly from the Fuchsia target.

From a development host

To record a trace for a Fuchsia target from a development host, run the following:

fx traceutil record component arg1 ... --with-base

fx traceutil record does the following:

  • Takes a 10 second trace on the Fuchsia target with the default options. This records basic graphics data and thread CPU usage.
  • Copies the trace from the Fuchsia target device to your development host.
  • Converts the trace data into a viewable HTML file.

If you specify a component, the component runs after tracing has started. This behavior is intended to not miss any early trace events in the component.

For a full list of the record option, run fx traceutil record --help.

Once you have trace file, you can now convert and analyze that trace file. For more information, see Converting and visualizing a trace.

From a Fuchsia target

To record a trace directly from a Fuchsia target, run the following in a shell on your target:

trace record

This saves your trace in /data/trace.json on your Fuchsia target by default. For more information on the trace utility, run trace --help at a Fuchsia shell.

Once you have trace file, you can now convert and analyze that trace file. For more information, see Converting and visualizing a trace.