How to use the Ubuntu Frame diagnostic feature

Ubuntu Frame now has an easy-to-use diagnostic screen that can be used to inform the user of any issues that have occurred when running your application. It allows the application to define which information is most useful to display to diagnose and fix any bringup issues or runtime errors.

Version 79: This feature is only available from Ubuntu Frame 79 onward. As of the time of writing, this version is still in beta.

Setup System

Make sure to install or refresh Ubuntu Frame.
To install:

snap install ubuntu-frame

For demonstration purposes in this how-to, we will be using a simple snap whose only purpose is to display user-inputted text on the diagnostic screen.

To install the demo snap:

snap install frame-diagnostic

Next, connect the ubuntu-frame-diagnostic plug from the demo snap to Frame’s ubuntu-frame-diagnostic slot so the two can communicate:

snap connect frame-diagnostic:ubuntu-frame-diagnostic ubuntu-frame:ubuntu-frame-diagnostic

Running the Demo

Launch Ubuntu Frame:

ubuntu-frame

In another terminal, run the demo snap:

frame-diagnostic "Hello, world!"

Now, without closing Frame, try writing something else.

frame-diagnostic "Goodbye, world!"

The text will update automatically when the diagnostic text changes.

How To Utilize Ubuntu Frame Diagnostic With Your Application

To learn how to implement Ubuntu Frame’s diagnostic screen, take a look at the demo app’s snap/snapcraft.yaml and notice the following entries:

plugs:
  ubuntu-frame-diagnostic:
    interface: content
    content: diagnostic-text
    target: $SNAP_COMMON/diagnostic
    default-provider: ubuntu-frame

environment:
  DIAGNOSTIC_FILE: $SNAP_COMMON/diagnostic/diagnostic.txt

plugs allows the sharing of content between two snaps. Here, there is a plug called ubuntu-frame-diagnostic that allows writing to the diagnostic file within Frame. In the target line, the directory inside the Ubuntu Frame snap that holds the diagnostic file is linked to this snap’s $SNAP_COMMON directory.

The environment section creates an environment variable called DIAGNOSTIC_FILE that points to the diagnostic.txt file which the diagnostic screen reads from.

In script/write_diagnostic, you can see the following:

#!/bin/sh
echo "$*" > "${DIAGNOSTIC_FILE}"

The only thing that the script does is write the user-inputted text to DIAGNOSTIC_FILE.

To enable diagnostic reporting in your application:

  1. Create a plug to link with Frame’s ubuntu-frame-diagnostic slot
  2. Create an environment variable pointing to Frame’s diagnostic file
  3. Write diagnostic information to the file located at the environment variable

The diagnostic screen will automatically update when it detects changes to the diagnostic file.

Configuration Options

To learn about Ubuntu Frame Diagnostic’s various configuration options, please refer to the configuration options reference.