Diagnostics Panel

The Diagnostics Panel is a client-side control that provides a set of built-in tools to help configure and troubleshoot client applications during the development phase.

This section describes how to add the panel to your client, and how to use the various tools once it has been added.

How-to

Add the panel to a client application

Adding the Diagnostics Panel is similar to adding a view on the client: you add it as a div in HTML5, using Storyboard in iOS, or as a layout in Android.

HTML5

In your .html file, you would add:

<div id="pwDiagnosticsPanel"></div>

The panel gets initialized on connect; to make this work, add the following in your .js file:

  •   a listener for connection state change event, for example:
    pureweb.listen(pureweb.getClient(), pureweb.client.WebClient.EventType.CONNECTED_CHANGED, onConnectedChanged);
  • a handler that runs the script to initialize the panel on connect:
    function onConnectedChanged(e) {
        if (e.target.isConnected()) {
            var diagnosticsPanel = document.getElementById('pwDiagnosticsPanel');
            if (diagnosticsPanel) {
                pureweb.client.diagnostics.initialize();
            }
        }
    }

iOS

To add the Diagnostics Panel in an iOS client, you add the necessary view controllers to your storyboard using Interface Builder (the controllers that you need can be found in the sample applications):

  1. Navigate to the source files for the sample client applications.
  2. Open the main storyboard for either the Scribble or Asteroids sample application.
  3. Select the following five controllers: DiagnosticsView, TabBar, TraceView, AppStateView, and OptionsView.

  4. Copy these scenes to the storyboard of your own application.
  5. Add a modal segue between the Diagnostics button and the DiagnosticsViewController.

Android

To add the Diagnostics Panel in an Android client, get the class files from a sample application, and inflate the relevant layout:

  1. Navigate to the source files for the sample client applications; the default location is:
    [install_path]\SDK\Samples\Android
  2. Find the files for the DiagnosticsPanel.java class and the diagnostics_view.xml layout, and copy them to your own project.
  3. Add the code to import the panel, inflate the layout, and display the panel in the user interface.

    //Import the panel.
    import pureweb.samples.DiagnosticsPanel;
    
    // Inflate the layout
    @Override
    protected void onConnected() {
        LayoutInflater inflater = (LayoutInflater)getSystemService(LAYOUT_INFLATER_SERVICE);
    						
        (...)
        
        final DiagnosticsPanel diagnosticsPanel = (DiagnosticsPanel)inflater.inflate(R.layout.diagnostics_view, null);
        diagnosticsPanel.setFramework(framework);
    }
    
    // Add the panel to the UI
    // The example below adds it as a tabbed view
    addTab("Diagnostics", diagnosticsPanel, new Action() {
        @Override
        public void invoke() {
            // NOOP
        }
    });
    

After you've added the panel in the code, do this to access the panel from your running client:

  • For browser-based clients, provide the _diagnostics=true parameter in the client URL.
  • For mobile app clients, it depends how you set up the user interface. For instance, in the sample applications, the panel is called by tapping a button labeled Diagnostics.

Navigate the tools

The Diagnostics Panel provides various tools across several tabs. The tools are the same in all client platforms, with the exception of the profiling tool, which is only available in HTML5.

Set encoding configuration on the fly

The Options tab of the Diagnostics Panel provides a user-friendly visual interface for manipulating the image mime type and quality, in both interactive and non-interactive mode, and to see on the fly the impact of these changes. It allows you to try out various configurations before committing to one in your code.

For more information on image encoding and interaction modes and how to set them programmatically, see Fine-tune the image encoding.

The settings from the Diagnostics Panel will not be saved when the session ends. If you are satisfied with a configuration change that you tried within the panel, you must implement it in your code .

  1. Select a mime type (image format) from the drop-down list for the interactive mode, and repeat for the non-interactive mode.
  2. Set a quality level value for the interactive mode by sliding the Quality cursor, and repeat for the non-interactive mode. Accepted values range from 0 (lowest quality) to 100.
  3. Click Apply to commit the changes.

Interact with the view to see the impact of the changes.


Toggle client-side command filtering

The Client side filtering checkbox in the Diagnostic Panel's Options tab provides a shortcut to toggle client-side command filtering on and off, and see the impact without the need to recompile. Filtering is enabled by default.

Client-side filtering is used to automatically filter out duplicate or redundant input event commands sent from the client to the service, thereby reducing bandwidth. For example, when drawing in the Scribble sample application, the client will send enough commands to the service to ensure the shape of the scribbles is displayed correctly, but will filter out the rest. This can prevent performance problems on the service side; an unfiltered sequence of consecutive mouse moves, for instance, could potentially trigger a expensive sequence of renders in the service.

In the APIs, this filtering is governed by the CommandFilter interface. The default implementation, DefaultCommandFilter, aggregates view resize and ping events, as well as mouse move and mouse wheel events. You can also create your own implementation of CommandFilter; see the API reference for more information.

Command filters do not filter any command that your client sends to the service using queueCommand.

The changes made in the Diagnostics Panel will not be saved when the session ends. If you want to programmatically disable or enable the client-side command filter, set the /PureWeb/ClientCommandFiltering element in application state to either true (enabled) or false.


View the trace log

The Trace tab displays any information that developers choose to trace within a client application. In the example below, the developer has chosen to trace color changes within the sample Scribble application.

By default, no information is traced. To set a trace, use the relevant method in the client API, as illustrated below:

HTML5

pureweb.client.diagnostics.trace("Your trace message");

iOS (Obj-C)

PWTraceLogger *logger = [PWTraceLogger sharedInstance];
[logger logMessage:@"Your trace message"]

Android

// PureWeb's Android API does not provide a method for setting up a trace; 
// instead, it relies on the logging classes provided by the native Android SDK.

The Diagnostics Panel’s Trace tab also offers some additional functionality:

  • To change the trace size (number of traced transactions stored in memory), type the desired size in the text box provided.
  • To reset the trace size back to the default value, click the Reset Trace Size button.
  • If the trace size is a value larger than can be displayed in the Trace tab, the system will display a scroll bar on the side, which can be used to navigate to the bottom and see the latest lines added to the trace. When the Autoscroll Trace check box is selected, the system will automatically scroll to the bottom.

View application state in real time

The AppState tab of the Diagnostics Panel allows you to see the application state tree at a glance. It is a great tool to quickly determine how user interactions in the client are reflected in application state.

The content of the tab is updated in real time. Simply perform operations in your client while the tab is displayed and see how the content of the application state tree changes accordingly.

Should the content of the tab not update automatically for whatever reason, click the Refresh button.


Test bandwidth and latency

The Bandwidth tab is used to test the network connection between the PureWeb server and the client application to measure latency and bandwidth and help assess network conditions.

To test latency, enter the number of iterations that should be included in the test and click the Test Latency button. The system will return results that include minimum, average, and maximum latency.

To test bandwidth, enter the number of payload bytes and click the Test Bandwidth button. The system will return results that include minimum, average, and maximum bandwidth.


Display a profiling report

The Profiling tab is available only in the Diagnostics Panel for HTML5 client applications.

Click the Enable Profiling checkbox to display a profiling report in XML format. This report contains measurements on how long it takes the PureWeb application to perform certain actions, such as building requests and parsing responses. It shows how much CPU time and bandwidth are consumed by various aspects of your application.

An example of this report is shown below.