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 which 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, also represent events from a Fuchsia system, but are fine grained, higher frequency and are meant for machine consumption to compute other insights and visualizations. When you combine structured logging and tracing it helps you diagnose, debug and troubleshoot diverse Fuchsia target devices more efficiently.

You should consider using tracing if you do not need to view data in real time and want the ability to:

  • Collect submicrosecond granular structured data.
  • Visualize data in an interactive viewer.
  • Query and aggregate data in SQL.

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: