Diagnostics and observability on Fuchsia

Fuchsia offers a variety of systems to observe a running Fuchsia system. Each observability system provides different information and tradeoffs. The observability systems are:

Logging

Logs play an important part in diagnostics as they describe human readable events that have happened on a Fuchsia system. In Fuchsia, a component can record log messages through the fuchsia.logger.LogSink protocol. sdk/lib/syslog/cpp and src/lib/diagnostics/log/rust are the supported libraries for recording logs on Fuchsia. These libraries provide the encoder implementation for things such as tags, structured key/value pairs, metadata, message, and fuchsia.logger.LogSink integration. For more information on how Fuchsia components can write logs, see Recording logs.

You should consider using logging if you want the ability to:

  • View low frequency messages and events that are human readable.
  • View the data in snapshots and other Fuchsia tools.

Tracing

Fuchsia's tracing system offers a comprehensive way to collect, aggregate, and visualize fine-grained diagnostic tracing information from Fuchsia user space processes and the Zircon kernel. Traces represent events from a Fuchsia system with submicrosecond precision, designed for high-frequency event recording and post-collection visual analysis.

When combined with the Perfetto UI, tracing allows you to see instants and durations visually along an interactive timeline.

You should consider using tracing if you want the ability to:

  • See instant milestones and duration slices visually on a timeline.

  • Measure precise submicrosecond latencies and identify execution bottlenecks.

  • Follow asynchronous operations and flow events across processes and threads.

  • Correlate user space execution with Zircon kernel scheduling events.

  • Query and aggregate trace data offline using SQL in the Perfetto Trace Processor.

Inspect

Fuchsia provides you with Inspect which enables Fuchsia components to expose structured diagnostic information about their current state. You can then use the ffx inspect tool to query this diagnostic information. For more information, see Fuchsia component inspection and ffx inspect.

You should consider using Inspect if you want the ability to:

  • Monitor the state of a component at a specific given time.
  • Represent information about the current state and recent history of a component.
  • Collect data for low-frequency snapshots of a component's state to enable fleet-wide metrics.
  • View the Inspect data in snapshots and tools.
  • Build visualizations, analysis, and create automated anomaly detection based on snapshots.

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.

When using Cobalt, it is recommended that your component is instrumented with Inspect. If your component is instrumented with Inspect, Sampler forwards Inspect diagnostics data to the Cobalt telemetry system for fleet monitoring.

For more information about Cobalt, see Cobalt: Telemetry with built-in privacy .

Snapshots

Fuchsia devices have the ability to capture snapshots that contain information about the current state of the entire system. This includes information about the Fuchsia build running on the system, kernel and system logs, and Inspect data from the system and its components. You can also capture a snapshot with the ffx target snapshot tool.

Detect

Additionally, Fuchsia devices run Detect which is able to trigger crash reports based on periodically snapshotting a subset of components Inspect data and checking for various conditions, which if true, then cause it to trigger a crash or feedback report.

Working with diagnostics and observability

As you work with Fuchsia logs, Inspect, and tracing to diagnose issues, you may want to use some of these tools:

  • ffx log to retrieve logs from a Fuchsia device.
  • ffx target snapshot to take a snapshot of a Fuchsia target devices's state.
  • ffx triage to analyze logs and inspect components from Fuchsia snapshots.
  • ffx inspect to query data exposed by components through the Inspect API.
  • ffx trace to collect, aggregate, and visualize diagnostics tracing information.
  • zxdb to debug your code that is running on Fuchsia. zxdb is a console-mode debugger for code running on Fuchsia.

You may also want to:

You can also follow the diagnostics codelabs:

You can also follow the tracing tutorials and guides: