Procedures

The document collects typical procedures helpful during 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 some operation with it failed, try to complete at least the finalizing task in that failed process. Only after that, you will be able to do something with the resource.

Note

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

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

1. In the provider control panel, navigate to Operations > Tasks and identify if 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 and thus allows 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 to narrow your search.

2. Investigate closely the execution output of the task. It makes sense not to 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 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
   

   Once the traced operation is completed, 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 some 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 custom tab does not show up in the control 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 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 out data that helps you isolated the cause of the issue. When a navigation request has failed, its response may contain explicit description of the problem. Typically it is “404 view with Id <view_id> not found”. The cause of such 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

In case 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 out the JavaScript file that requires investigation. It must be inside one of subfolders inside 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 have to do a lot of edit-and-test operations. It would be time consuming to go through the normal application update process. This section explains how to update the code on the system in the most efficient way before you release the APS package.

Preliminary, it requires:

1. Ensure the Development Mode is enabled on the system.
2. Identify the Package Location on the management node.
3. Identify the Package Location on the endpoint host.

Note

If you change an APS type, you have to 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, deployment guide

If you changed metadata or JavaScript code, you should refresh the control panel on the browser 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.

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

← Debugging

Examples →