Troubleshooting tools reference

The purpose of this page is to guide users towards tools that may solve common questions that a Fuchsia developer may have.

Problems

  • I want to understand what my component is doing at runtime.

    • Inspect

      • Expose structured diagnositcs information about the state of a component. This helps to monitor the state of a component at an given point in time. The Inspect tool allows a component to expose an arbitrary hierarchy of typed key/value pairs and update it over the course of its execution. This data can be snapshotted and inspected while the component is still running. Inspect is commonly used to represent information about the working set and recent history of a component to help during debugging. A component developer can use Inspect by depending on a library in their language of choice (Rust, C++), and calling the appropriate methods to mutate their recorded state. Inspect data may be read using the ffx inspect tool or ffx target snapshot.

    • Logs

      • Print string logs during the execution of a component. Fuchsia, like many systems, supports basic logging of strings to record some information when particular lines of source code are executed. Logs are aggregated by the Archivist component. They may be read using `ffx log`.

    • Structured Logs

      • Store structured key/value pairs in log messages. In addition to text-based logs, Fuchsia supports fully structured log records encoded as typed key/value hierarchies. Developers may write structured logs using the tracing crate macros in Rust or the FX_SLOG macro in C++.

    • Tracing

      • 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.

    • zxdb

      • zxdb is a console-mode debugger for native code running on Fuchsia.

  • I want to automatically post-process snapshots to identify notable values or error conditions

    • Triage

      • Triage selects and processes values from Diagnostics data, producing useful actions and insights on-device and off-device. Triage can: display calculated values; file snapshots (when running on-device as the engine of Detect); and print warnings about off-nominal values.

  • I want to automatically trigger taking a snapshot on a specific condition

    • Detect

      • Detect scans Inspect data on-device to decide when to file crash reports. Detect scans are configured using the Triage language and run every few minutes.

  • I want to measure the runtime of specific functions

  • I want to collect metrics from user-owned devices in the field

    • Cobalt

      • Cobalt is a pipeline for collecting metrics data from user-owned devices in the field and producing aggregated reports. Cobalt includes a suite of features for preserving user privacy and anonymity while giving product owners the data they need to improve their products.

Tools

  • Expose structured diagnositcs information about the state of a component. This helps to monitor the state of a component at an given point in time. The Inspect tool allows a component to expose an arbitrary hierarchy of typed key/value pairs and update it over the course of its execution. This data can be snapshotted and inspected while the component is still running. Inspect is commonly used to represent information about the working set and recent history of a component to help during debugging. A component developer can use Inspect by depending on a library in their language of choice (Rust, C++), and calling the appropriate methods to mutate their recorded state. Inspect data may be read using the ffx inspect tool or ffx target snapshot.

    Problems that Inspect can solve:

    • I want to understand what my component is doing at runtime.
    • Triage

  • Print string logs during the execution of a component. Fuchsia, like many systems, supports basic logging of strings to record some information when particular lines of source code are executed. Logs are aggregated by the Archivist component. They may be read using `ffx log`.

    Problems that Logs can solve:

    • I want to understand what my component is doing at runtime.
    • Structured Logs

  • Store structured key/value pairs in log messages. In addition to text-based logs, Fuchsia supports fully structured log records encoded as typed key/value hierarchies. Developers may write structured logs using the tracing crate macros in Rust or the FX_SLOG macro in C++.

    Problems that Structured Logs can solve:

    • I want to understand what my component is doing at runtime.

  • Persistence stores Inspect data and publishes it on the subsequent boot. Sometimes Diagnostics data can't be exported from the device until it's rebooted, for example, if there's a problem with networking. Persistence writes selected Inspect data to disk and then publishes it back to Inspect on the next boot.

    Problems that Persistence can solve:

    • Inspect

  • Sampler reads data from Inspect and forwards it to Cobalt. Sampler provides an easy way to send data to Cobalt. Instead of linking your app to the Cobalt service and using it directly, you can just publish your data in Inspect and write a simple config file entry to tell Sampler to fetch your data and send it to Cobalt.

    Problems that Sampler can solve:

    • Inspect

  • 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.

    Problems that Tracing can solve:

    • I want to understand what my component is doing at runtime.
    • I want to measure the runtime of specific functions
    • Inspect
    • Logs

  • Triage selects and processes values from Diagnostics data, producing useful actions and insights on-device and off-device. Triage can: display calculated values; file snapshots (when running on-device as the engine of Detect); and print warnings about off-nominal values.

    Problems that Triage can solve:

    • I want to automatically post-process snapshots to identify notable values or error conditions
    • Inspect
    • Detect

  • Cobalt is a pipeline for collecting metrics data from user-owned devices in the field and producing aggregated reports. Cobalt includes a suite of features for preserving user privacy and anonymity while giving product owners the data they need to improve their products.

    Problems that Cobalt can solve:

    • I want to collect metrics from user-owned devices in the field

  • Detect scans Inspect data on-device to decide when to file crash reports. Detect scans are configured using the Triage language and run every few minutes.

    Problems that Detect can solve:

    • I want to automatically trigger taking a snapshot on a specific condition
    • Inspect
    • Triage

  • zxdb is a console-mode debugger for native code running on Fuchsia.

    Problems that zxdb can solve:

    • I want to understand what my component is doing at runtime.