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 state about a component. Monitor the state of a component at an instant 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. Component authors use Inspect by depending on a library in their language of choice (Rust, C++, and Dart are currently supported), and calling the appropriate methods to mutate their recorded state. Inspect data may be read using the ffx component 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++.

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

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

Tools

  • Expose structured state about a component. Monitor the state of a component at an instant 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. Component authors use Inspect by depending on a library in their language of choice (Rust, C++, and Dart are currently supported), and calling the appropriate methods to mutate their recorded state. Inspect data may be read using the ffx component 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

  • 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 trigger taking a snapshot on a specific condition
    • I want to automatically post-process snapshots to identify notable values or error conditions
    • Inspect
    • 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.

    Problems that Detect can solve:

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