Rendering (visualizing) a topology

You define the scope of the topology that you want to render by specifying a seed resource, the number of relationship hops surrounding that resource, as well as the types of hops. The topology service then supplies the data that is required to visualize the topology.

Before you begin

To visualize a topology, ensure that inventory integrations are configured.

Note: The IBM Cloud Pak for AIOps console has a default timeout set at 30 seconds. If service requests are not received in that time, a timeout message is shown, as in the following example:

A time-out has occurred. No response was received from the Proxy Service within 30 seconds.

For more information, see Topology render timeout.

Tip: For information about using the File and REST SDK observers to build custom topologies, see Building a custom topology.

Procedure

Log in to the IBM Cloud Pak for AIOps console.
Open the Resource management page from the main navigation menu.

Resources are displayed arranged in Applications, Resource groups, and Resources tabs. Both the Search and Filtering functionality is accessible at the top left.
Find a resource to use as the seed resource of the topology visualization.

You can find the required seed resource within existing applications (services), resource groups or resources, or use the filtering or search functionality to identify it.

Search: As you type in a search term that is related to the resource that you want to find, such as name or server, a drop-down list is displayed. This contains the suggested search terms that exist in the topology service. If the resource that you want to find is unique and you are confident that it is the first result in the list of search results, you do not need to select a result from the suggested search terms. Instead, choose to click the View topology for closest matching resource icon in the Suggest drop-down. This renders and displays the topology for the closest matching resource.

For more information on searching and filtering, see the Resource management: Searching and filtering topic.

For more information about advanced query syntax, see the topology query reference topic.

If you select one of the suggested results, the Search Results page is displayed listing possible resource results. The Results are listed under separate Resources and Groups tabs.
- Deleted resources
  
  You can select the Include deleted resources toggle in order to include deleted resources in the Results page (unless an administrator has disabled that feature). Deleted resources are marked as such, and the date and time that they were deleted is displayed.
  
  If you click View topology, the resource is displayed in the Topology Viewer with the history timeline open, and set to 1 ms before deletion. When closed, the topology is cleared. If you display applications (services) or resource groups as topologies, the Incidents panel is opened by default on the right hand side. You can close the panel to maximise the topology display area, or switch from a graphical topology view to a tabular view.
  
  When you search for resources with a previous point in time set in the history timeline, deleted resources are not returned and the toggle to include them is not available.
  
  Deleted templates or defined topologies are not included in any search results.
- Groups
  
  Groups must be defined before they are listed. If you are defining Group templates in the template builder, search results are listed under separate Resources and Groups tabs.
  
  To designate as a favorite a group search result and add it to the collection of topologies accessible from the Resource management page, tag it as a favorite by selecting the Add to favorites icon next to it.
- Tabular view
  
  Resource groups and applications (services) can be displayed in table format, which lists the included resources alphabetically.
For each result, the name, type and other properties are displayed.

If a status other than clear exists for a search result, the maximum severity is displayed in the information returned. Also, a color-coded information bar before each result displays all non-clear statuses (in proportion).

You can expand a result in order to query the resource or defined topology further and display more detailed, time-stamped information. Examples of this include its state and any associated severity levels, or when the resource was previously updated or replaced (or deleted).

You can click the View Topology button next to a result to render the topology.

Restrictions:
- When you load a predefined topology, it is displayed in a 'group' version of the Topology viewer, which has restricted functionality. You are unable to follow its neighbors, or change its hops, or use its advanced filters.
- You can recenter the defined topology from the context menu, which loads it in the Topology viewer with all its standard functionality.
Select a number to define the number of relationship hops to be visualized from the seed resource. The default value is set at 1.

For more information about customizing the maximum hop count, see Configuring advanced settings.
Choose one of the following hop types:
- The Host to Host hop type uses an aggregate traversal across elements with the entity type 'host' to generate a view that shows host to host connections.
- The Element to Element hop type (default) performs the traversal by using all element types in the graph.
- The Element to Host hop type provides an aggregated hop view like the 'Host to Host' type, but also includes the elements that are used to connect the hosts.
For more information about customizing the hop type, see Configuring advanced settings.
Filter the topology before rendering it.

Open the Filter toolbar by using the Filter toggle, and apply the resource, relationship, or severity filters required. You can filter resources that are displayed in the topology, or set filters before rendering a topology to prevent a large, resource-intensive topology from being loaded. If a filter is applied to a displayed topology, the text 'Filtering applied' is displayed in the status bar under the topology.

For more information about using filters, see Viewing a topology.
Click Render to render the topology.

The Topology viewer connects to the topology service and renders the topology. By default, the view is refreshed every thirty seconds, unless specified otherwise.

What to do next

Next, you can refine and manipulate the view for further analysis.

If needed, you can rebuild a topology. For instance, open a topology and use the visualization tools to modify the topology settings and then clicking Render. This action runs the topology visualization to render the topology based on your new settings.

Tip - Incidents: The topologies of applications (services) and resource groups are displayed with the Incidents panel open on the right hand side, which you can collapse to increase the topology display area. If you switch to a tabular view and use the Incidents panel functionality to sort or filter the incidents, the table is dynamically updated to display only the resources affected by the selected incidents.

Troubleshooting: Topology render timeout

If you receive a timeout message, this can be due to a number of reasons:

Large amounts of data being retrieved for complex topologies
Too many hops counts specified
Issues with the back-end services

Workarounds

Check that all services are running.

You can verify that the containers are running by using the following command:
```
oc get pods -n <namespace> | grep <pod_name>
```
The system should return text indicating that all containers have a state of Up.
Increase the timeout when rendering topology views. The Red Hat OpenShift route used when rendering topologies in the UI has a default timeout of 30 seconds, which might not be long enough to render a large or complex topology view. To increase the timeout value, for example to 300 seconds, add the following code to the spec section of the custom resource of the operator (which is usually the asm instance; you can find the instance name using the oc get asm command):
```
spec:
   helmValuesASM:
      global.asm.uiApi.topologyServiceTimeout: 300
      global.asm.uiApi.layoutServiceTimeout: 300
```
The up-api pod should restart with the values of the environment variables TOPOLOGY_SERVICE_TIMEOUT and LAYOUT_SERVICE_TIMEOUT now set to 300 seconds.

You can list the routes by using the oc get routes command. To increase the timeout for the UI change, use the following example:

oc annotate route noi-ui-api --overwrite haproxy.router.openshift.io/timeout=300s
oc annotate route noi-ibm-hdm-common-ui-uiserver --overwrite haproxy.router.openshift.io/timeout=300s

Lower the hop count to reduce the service load. For more information about customizing the maximum hop count, see the Defining advanced topology settings topic.

Troubleshooting: No results found

When you enter text into the Resource management field, surround the text with quotation marks, such as in "Search value". If the quotation marks are omitted, topology viewer doesn't display results even if the search value was included as data.