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 required to visualize the topology.

Before you begin

To visualize a topology, your topology service must be running, and your Observer jobs must be active.

About this task

You use this task to render a topology based on a specified seed resource.

Note: The UI 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.
See Topology render timeout for more information on addressing this issue.

Procedure

Access a topology view via the Resource management page.
Use the Search field to find a seed resource around which to build your topology.
Find a resource using the Search field.

Search

As you insert your cursor into the Search field, the five most recent searches are listed, and can be selected. You can delete a recent search by clicking the delete button (X) to the right of the suggested search, or click View all to display all recent searches. When viewing all recent searches, you can filter the results further using a Search field, or select them and then delete them from the recent searches list.

As you type in a search term, suggested search results are listed, both from the topology database and from recent searches, with your entered text highlighted.

For information on advanced query syntax, see the inventory query reference topic.

When you click a search result, the results are listed under the Favorites and All results sections, separated into Applications, Resource groups and Resources tabs, and search is closed.
Deleted resources: For resources only, you can select the Include deleted resources toggle in order to include deleted resources on 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 1ms before deletion. When closed, the topology is cleared. 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.

For each search result, the application, resource group or resource 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, and a color-coded information bar above each result displays all non-clear statuses (in proportion).

For resources only you can click More details to display additional information on the Resource details sidebar, such as its state and any associated severity levels, or when the resources were previously updated or replaced (or deleted).

To render a topology, click the name link.
Resource group restriction: When you load a resource group topology, you are unable to follow its neighbors, or change its hops, or make use of its advanced filters.

Tip: While viewing a topology, you can click View legend to open a Help panel that describes the visual elements used in the display of the topology.
Filter the Search results by defining filter conditions.
Filter conditions

The Resource management page can display a large number of resources, resource groups or applications, which you can filter using the Filter conditions panel.
Restriction: Setting filter conditions for search results is currently only available for on-prem systems.

Click Open filter to the left of the Search field to display the panel, then define the filter properties.
Business criticality

If defined, you can select criticalities to reduce the number of items displayed in the Results table.

Other properties

To add additional filter properties, click Add conditions+.
Note: The default Filter builder properties are 'entityTypes', 'name' and 'tags'. An administrator can add additional properties for filtering when configuring advanced topology search settings.

Select a property from the Choose a property drop-down.

Select an operator appropriate to that property from the Choose an operator drop-down.

Depending on the property selected, either type in a value or select one using the Value field (or drop-down).

Click Apply to filter the Results table.

You can delete, edit or disable the condition, or add additional ones.
Tip: Any filter conditions you set are maintained in the URL, and can therefore be shared via direct-launch URL string.

Example 1: Select the 'tags' property, then the 'excludes all' operator, then choose one of the available tags from the Value drop-down. Once applied, all results with that tag are excluded from the Results table.

Example 2: Select the 'name' property, then the 'equal to' operator, then type a resource name into the Value field. Once applied, only results of that name are included in the Results table.

From the Navigation toolbar, perform the following actions:

Choose number of hops.

Number of hops

The number of relationship hops to visualize from the seed resource, with the default set at 'one'.

You define the number of relationship hops to be performed, which can be from zero to four, unless this setting has been customized. See the Defining advanced topology settings topic for more information on customizing the maximum hop count.
Choose hop type.

Type of hop

The type of graph traversal used. The options are:

Element to element hop type

This type performs the traversal using all element types in the graph.

Host to host hop type

This type generates a view showing host to host connections.

Element to host hop type

This type provides an aggregated hop view like the Host to Host type, but also includes the elements that are used to connect the hosts.
Tip: The URL captures the hopType as 'e2h'. When launching a view using a direct URL, you can use the hopType=e2h URL parameter.
Filter the topology before rendering it.
The Filter toolbar is displayed as a panel on the right-hand side of the page, and consists of a Simple and an Advanced tab. If selected, each tab provides you with access to the following expandable lists of filters:
- Resource types
- Relationship types
- Resource severity
Any resource or relationship types that have been excluded from view in order to optimize performance when rendering topologies are listed here. The seed resource of a topology can not be blocked, and neither can resource groups.
Note: You can override the exclusion using the context menu functionality.
- If you are filtering a topology before rendering it: All types are displayed, except those that have been excluded. After rendering the topology, you can toggle the Show all types switch so that only types relevant to your topology are displayed.
- If you are filtering a topology already displayed in the viewer: Only types relevant to your topology are displayed, for example host, ipaddress, or operatingsystem. You can toggle the Show all types switch so that all types are listed (apart from the excluded types).
Simple tab

When you use the Simple tab, all specified types are removed from view, including the seed resource.

It only removes the resources matching that type, leaving the resources below, or further out from that type, based on topology traversals.

By default, all types are On. Use the Off toggle to remove specific types from your view.

Advanced tab

The Advanced tab performs a server-side topology-based filter action.

If you change the topology, you can set filters before you render the topology to prevent a potentially large, resource-intensive topology from being loaded in full.
It can exclude or include types:

Exclude removes the resources matching that type, as well as all resources below that type. However, the seed resource is not removed from view, even if it is of a type selected for removal.

Include displays the selected types in the topology.
Tips

Reset or invert all filters: Click Reset to switch all types back on, or click Invert to invert your selection of types filtered.

Hover to highlight: When a topology is displayed, hover over one of the filtering type options to highlight them in the topology.
Click Render to render the topology.

Results

The Agile Service Manager topology viewer connects to the topology service and renders the topology. By default the view is refreshed every thirty seconds, unless specified otherwise (by an administrator user).

Troubleshooting: Topology render timeout: If you receive a timeout message, this may be due to a number of reasons:

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

The workaround is to increase the timeout when rendering topology views.

Workaround (on-prem)

Check that all services are running smoothly. You can verify that the docker containers are running using the following command:
```
$ASM_HOME/bin/docker-compose ps
```
The system should return text indicating that all containers have a state of Up.
Lower the hop count to reduce the service load. See the Defining advanced topology settings topic for more information on customizing the maximum hop count.
An administrator user can increase the default 60 seconds timeout limit by changing the following setting in the $ASM_HOME/.env file:
```
LAYOUT_SERVICE_TIMEOUT=60
```
If increasing this to two minutes or more, you should also increase the timeouts used by the proxy. Change proxy_read_timeout 120 in the following files:
- /opt/ibm/netcool/asm/etc/nginx/conf.d/nasm-ui-api.rules
- /opt/ibm/netcool/asm/etc/nginx/conf.d/nasm-layout.rules
You must restart Agile Service Manager for the changes to take effect:
- To stop Agile Service Manager, run:
```
<ASM_HOME>/bin/asm_stop.sh
```
- Once stopped, re-start Agile Service Manager:
```
<ASM_HOME>/bin/asm_start.sh 
```

Workaround (OCP)

The OpenShift route used when rendering topologies in the UI has a default timeout of 30 seconds which may not be long enough to render a large or complex topology view. To increase, for example to 300 seconds, add the following code to the spec section of the custom resource of the operator:
```
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.

List the routes using the oc get routes command and increase the timeout for the UI change:

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

Increase the timeout for the Topology and Layout Swagger pages, as in the following example:

oc annotate route noi-topology-topology --overwrite haproxy.router.openshift.io/timeout=300s
oc annotate route noi-topology-layout --overwrite haproxy.router.openshift.io/timeout=300s

Troubleshooting: No results found

Workaround: 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.

What to do next

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