docs/development/tracing/README.md

# Fuchsia tracing guides

The [Fuchsia tracing system][fuchsia-tracing-system] allows you to collect and
visualize diagnostic information from Fuchsia components.

Fuchsia's tracing system offers a comprehensive way to collect, aggregate, and
visualize diagnostic tracing information from the Fuchsia user space processes
and the Zircon kernel. Traces, like logs, represent events from a Fuchsia
system, but are fine grained, higher frequency and are meant for machine
consumption to compute other insights and visualizations.

Tracing and profiling are a powerful pair of tools to gain insights into the
performance of a system. In comparison to profiling which samples data every
so often, tracing captures every event in a short duration and can include extra
information with the trace event.

Generally, [profiling][fuchsia-profiling] is more useful if you don't know where
the problem is, and aren't sure where to put trace spans, or you aren't able to
add tracing events.

Tracing involves three high-level steps:

* Instrument: Instrument your code so that you can measure the runtime of
  specific functions by surrounding these pieces of code with trace events and
  add labels to emit during a trace.
* Record: Configure and start a tracing tool (`ffx trace`) to generate a trace.
* Analyze: Visualize the report with a UI such as Perfetto to identify issues
  and potential ways to optimize your code.

## General

* [Use trace events][use-trace-events]: This document explains the various types
  of tracing events that Fuchsia supports and how to use them in your
  components.

Fuchsia recommends that you use the [Perfetto UI][perfetto-ui] to view the
traces that you collect from Fuchsia components. For more information on using
Perfetto, see the [Perfetto documentation][perfetto-docs].

## Tutorial

If you're new to tracing, see [Tutorial on Fuchsia tracing][tracing-tutorial].

This tutorial provides a high level overview of tracing and the steps necessary
to add tracing to your Fuchsia components.

## Advanced guides

These guides are for advanced users who already understand the basics
of tracing in Fuchsia:

* [Tracing booting Fuchsia](/docs/development/tracing/advanced/recording-a-boot-trace.md)
* [CPU performance monitor](/docs/development/tracing/advanced/recording-a-cpu-performance-trace.md)
* [Kernel tracing](/docs/development/tracing/advanced/recording-a-kernel-trace.md)
* [Asynchronous tracing](/docs/development/tracing/advanced/tracing-asynchronously.md)

<!-- Reference links -->

[fuchsia-tracing-system]: /docs/concepts/kernel/tracing-system.md
[tracing-tutorial]: /docs/development/tracing/tutorial/README.md
[use-trace-events]: /docs/development/tracing/trace_events.md
[perfetto-ui]: https://ui.perfetto.dev/
[perfetto-docs]: https://perfetto.dev/docs/
[fuchsia-profiling]: /docs/development/profiling/profiling-cpu-usage.md