Client Troubleshooter

Summary

The Buendia client includes a troubleshooter and diagnostics framework for helping the user diagnose and fix issues within the application. This document describes the troubleshooter architecture as well as known issues.

Architecture

The backend of the diagnostics framework is made up of the following components, all of which reside in the diagnostics package:

• HealthIssue - represents a single detected problem (e.g. invalid username/password)
• TroubleshootingAction - represents the recommended user action to resolve a HealthIssue
• Troubleshooter - aggregates reported HealthIssues and posts sticky events with the recommended actions to resolve them (sticky events are essentially global state that remain until explicitly removed or overwritten)
• HealthCheck - when run, checks for one or more HealthIssues and posts an event whenever an issue is discovered or resolved; HealthChecks typically recheck for issues after a specified interval, but this is left to individual implementations
• HealthMonitor - runs all registered HealthChecks, notifying the Troubleshooter when any issue is reported as discovered or resolved

The recommended actions posted by the Troubleshooter are handled by ui/BaseActivity, which shows a "snackbar" at the bottom of the screen with a message and call to action that relates to the recommended action (this snackbar may also be shown for update notifications).

Known Issues

Snackbar persistence across activities

Switching activities hides the snackbar. The snackbar is eventually reshown, but this can cause some confusion for the user.

Snackbar is hidden by ProgressFragment

ProgressFragment is a fragment that manages state and shows a spinner when it is in the LOADING state. Switching to (or starting in) the LOADING state, however, hides any current snackbar. This is particularly a problem during initial sync, where the LOADING state may persist for an extended period of time. In this case, if there is a problem, the user may never be notified.

Snackbar briefly lingers

Because most health checks run every in intervals of several seconds, a snackbar may not disappear right away even when the user has solved the underlying problem. This is minor, as this lingering should only last a maximum of a few seconds, but it is potentially confusing.

No allowance for multiple messages/actions

BaseActivity chooses at most one snackbar message and action to display, so the user is not notified of multiple issues or may miss update notifications when a problem is present. Short-term, having a way to dismiss snackbar messages would be useful. Long-term, it may be worth considering a way to display multiple messages without overwhelming the user (perhaps a "notification drawer" for the snackbar?).