Procedures

This document covers typical procedures that are helpful during APS application troubleshooting and debugging.

Diagnostics of Failed Backend Tasks

As mentioned in the Task Manager section, a scheduled APS process may contain initiating, provisioning/unprovisioning, and finalizing tasks.

When a process over a resource is started, the APS controller changes the resource status from the aps:ready to another, typically aps:provisioning or aps:unprovisioning. This protects the resource from starting another process with it. The APS controller returns the resource status back to aps:ready by means of the finalizing task. It means you cannot do any operations with the resource until that final task is completed. For example, if you need to remove a resource because an operation with it failed, try to complete at least the finalizing task in that failed process. You will be able to do anything with the resource until the finalizing task is complete.

Note

Be careful when canceling tasks. It is better to cancel failed tasks one by one, than to cancel the whole tree of tasks that depend on each other. This may allow you to complete at least the finalizing task so that you remove the resource.

Diagnostics may consist of several steps. You can finish it on any of the following steps after you clarify the cause of an error.

1. In the provider control panel, navigate to Operations > Tasks and identify whether there is a task related to your issue. There are many search and sort criteria that you can use:

   • Status allows you to find tasks by their status, for example, to find all Rescheduled or Failed tasks.

   • Name contains the APS application name, allowing you to use a partial name pattern to filter the tasks.

   • Sorting by ID helps you to find the latest tasks.

   • Queue name helps you filter all APS tasks by the aps_application_instance prefix. It also contains the instance ID and subscription ID for narrowing your search.

2. Investigate closely the execution output of the task. Do not close the screen with this output if you think that some key words in it may help you in your further investigation of backend logs.

3. Get connected to the management node through SSH.

4. Investigate the respective REST operations in the apsc.http.log file. If you can repeat the operation, usually by running the failed task, print out the log tail with the new appended data. The following command will capture all new log messages and save them in the test.log file:

   # tail -fn0 /var/log/pa/apsc.http.log > test.log
   

   After the traced operation is finishes, stop the above command execution by pressing the CTRL+C combination on your keyboard and then open the test.log file to investigate the collected data. Keep in mind the log structure and use the following recommendations:

   • Search by words or phrases from the task execution message.

   • Search by the REST operation: “POST”, “PUT”, “GET”, or “DELETE”.

   • If a REST response contains “500 Internal Server Error”, the fault is on the application endpoint side.

5. To narrow your search, you can send a REST request in the command line interface from the management node.

6. Get connected to the endpoint host through SSH.

7. Investigate the Apache error log. Try to identify which custom PHP method caused the issue.

8. Search for the incorrect code in the suspected PHP file located in the application endpoint folder. To get more details in the error log, use the Development Mode in the PHP script. To localize the error, print more custom data by using the APS PHP Logger class.

9. To narrow your search, you can send a REST request in the command line interface from the endpoint host.

Diagnostics of Failed UI Navigation

If an application’s custom tab is not displayed in the user panel or an application custom operation does not forward users to the expected view, such failures refer to the navigation categories.

As explained in the introduction to navigation, navigation in a control panel can be static, as specified by the <navigation> section in APP-META.xml, and dynamic, when the custom code forwards a user to a certain view by calling a navigation method, for example, aps.apsc.gotoView(...).

Typical causes of failures in static navigation declared in APP-META.xml:

• Incorrect declaration of the <place-to> element, for example, referring to an incorrect placeholder.

• Incorrect declaration of a navigation variable or absence of the resource that the variable requires.

Typical diagnostic steps are as follows.

1. If there is an error when navigating inside the application UI, use the Network tab in your debugging tool. Pay attention to the failed navigation requests:

   POST /aps/2/navigation
   

   Typical diagnostic steps here are:

   • Click on the found request in the list to open the detailed view of the request in the right pane.

   • On the Headers tab, analyze navigation request headers, request payload, and response headers.

   • On the Preview tab, analyze the navigation response. On the Response tab, you will find the same in the raw JSON format.

   Most probably, you will isolate the error and can start resolving it in the code. Otherwise, continue the diagnostics by following the other steps in this procedure.

2. Establish an SSH connection with the management node.

3. Open the Platform UI Log to investigate the issue. If possible, repeat the navigation operation, for example by refreshing the browser, and watch the new added data in the log. For this purpose, catch the file tail and save it in a file as follows:

   # tail -fn0 /var/log/pa/pui/pui.log > test.log
   

4. Keep in mind the log structure to find data that helps you isolated the cause of the issue. When a navigation request fails, its response may contain an explicit description of the problem. Typically it is “404 view with Id <view_id> not found”. The cause of such a failure is a malformed request for an invalid placeholder ID or a request for a non-existent view.

5. To ensure you have identified the cause, try the respective navigation request using a special REST client or the command line interface.

Diagnostics of Failed UI Operations

If you experience a UI issue other than a navigation issue, follow these typical diagnostic steps. Most of them require the Debugging Tools in Browser. In the Chrome DevTools, it looks as follows.

1. On the Console tab, search for an error message.

2. Usually, an error message contains a link to the line in the source JavaScript code that caused the error.

3. On the Network tab, search for failed REST requests. If you find such a request, open its detailed profile and investigate its request and response.

4. On the Source tab, find the JavaScript file that requires investigation. It is inside one of subfolders of the /aps/2/packages/ folder.

5. Use Breakpoints, Data Watch, and Console Commands to isolate the issue in the JavaScript code.

Runtime Code Changes

When debugging a code, you must do many edit-and-test operations. The usual application update process is too time consuming. This section explains how to update the code on the system in the most efficient way before you release the APS package.

Preliminarily, it requires that:

1. ref:debug_tools_mn_devmode is enabled on the system.

2. The Package Location on the management node is identified.

3. The Package Location on the endpoint host is identified.

Note

If you change an APS type, you must go through the normal application update process.

Presentation Logic

Changes in the presentation logic can be done by editing the respective files directly on the management node, in the Package Location:

• Metadata in the APP-META.xml file, for example, navigation section

• JavaScript and related files, for example, JSON files, in the ui/ folder

• Images, for example, icons, and other custom files, for example, the deployment guide

If you changed metadata or JavaScript code, you need to refresh the user panel on the browser for it to take effect.

Provisioning Logic

If you change the provisioning logic of the APS application instance in the scripts/ folder, apply the changes directly in the Package Location on the endpoint host.

If the changes do not take effect immediately, remove the typeCache/ subfolder.

← Debugging

Examples →