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

  1. Access a topology view via the Resource management page.
    Use the Search field to find a seed resource around which to build your topology.
  2. 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 the Filter table Search field, or you can 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.
    Tip: 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 services, Resource groups and Resources tabs, and search is closed with the search term displayed. Click the delete button (X) to the right of the search term to return to the previous Resource management screen.
    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 service, 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. Alternatively, you can click Tabular view to display the topology of a service or resource group in table format instead.
  3. Filter the Search results by defining filter conditions.
    Filter conditions
    The Resource management page (or Resource map) can display a large number of resources, resource groups or services, which you can filter using the Filter conditions panel. Filters reduce the number of items displayed in the Results table as you define them, and you can save them for future use.
    Click Open filter to the left of the Search field to display the panel. If filters were defined and saved previously, you can select them from the Select a filter drop-down list.
    You define filter conditions using the default, or previously customized, Severity, Business criticality, or Other properties filters.
    Tip: You can select an existing filter and save it as a new filter, which you can then edit.
    For resources only: You can apply the filters you set to a specific moment in time by using the Historical search setting. Alternatively, you can display resources changed during a specified period using the Last updated setting.
    Severity
    Select one or more severity as a filter condition.
    Business criticality
    Select a business criticality as a filter condition.
    Business criticality can be customized by an administrator as described in Defining business criticality.
    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.
    Define a filter condition
    1. Select a property from the Choose a property drop-down.
    2. Select an operator appropriate to that property from the Choose an operator drop-down.
    3. Depending on the property selected, either type in a value or select one using the Value field (or drop-down).
    4. Click Apply to filter the Results table.
    You can delete, edit or disable the filter, or save it for future use.
    Tip: Any filter conditions you set are maintained in the URL, and can therefore be shared via direct-launch URL string.
    Examples:
    • 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.
    Save a filter
    1. Click Save as new filter on the overflow menu.
    2. Define a Filter name and Description for the filter. The name must be unique.
    3. Define the filter user and their level of access.
      • Only me: Select for private use.
      • Everyone: Select Use or Edit. If you select Edit, everyone will be able to change the filter.
      • Specified users, user groups or both: Select from the available Users or User groups, and then specify the level of control:
        • Use
        • Use and edit
        • Use, edit and manage
    4. Click Save as new filter.
    The specified users will be able to select the filter from the Select a filter drop-down list.
    Delete filters: You can delete only the filters that you have created. To do so, select Delete filter from the overflow menu.
    Geospatial (resources only)
    Select one of the following options from the Scope drop-down.
    Remember:
    If filtering from the Resource management page
    The Services and Resource group tabs are unavailable (grayed out). Once you have identified a resource you wish to view on a map (defined earlier), click the map icon for that resource in the table (to the right of the 'More details' link).
    If filtering from a Resource map
    Filters are applied immediately and the map is adjusted.
    All resources with geospatial data
    All resources that have geospatial properties are displayed.
    The Area filter parameter is unavailable.
    All resources without geospatial data
    All resources without geospatial properties are displayed.
    The Area filter parameter is unavailable.
    Within area
    Click Select area to open a world map. Use the cursor and zoom function to move to a desired location, then use the selection tool to specify the area. Click Apply selection to return to the previous screen, where all resources that have geospatial properties and are located within the selected area are listed.
    From here, you can clear or edit the area.
    Outside area
    Click Select area to open a world map. Use the cursor and zoom function to move to a desired location, then use the selection tool to specify the area. Click Apply selection to return to the previous screen, where all resources that have geospatial properties and are located outside the selected area are listed.
    From here, you can clear or edit the area.
    Include resources in overlapping area
    Click Select area to open a world map. Use the cursor and zoom function to move to a desired location, then use the selection tool to specify the area. Click Apply selection to return to the previous screen, where all resources that have geospatial properties and are located within the selected area are listed, as are resources adjacent to or overlapping with the selected area.
    Exclude resources in overlapping area
    Click Select area to open a world map. Use the cursor and zoom function to move to a desired location, then use the selection tool to specify the area. Click Apply selection to return to the previous screen, where all resources that have geospatial properties and are located within the selected area are listed, though resources adjacent to or overlapping with the selected area are excluded.
    Last updated (resources only)
    You can choose to display only the resources that were created or changed during a specific time period (prior to 'now').
    Exceptions: Changes in severity or status in this time period are not flagged.
    Choose either minutes, hours, or days, and select a number between 1 (one) and 500.
    Historical search (resources only
    You can choose to display only the resources that matched your filters at a specific historical moment.
    Choose a specific date and time in the past, and click Apply.

From the Navigation toolbar, perform the following actions:

  1. 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 a maximum of four, unless this setting has been customized.
    See the Topology rendering section in the 'Defining advanced topology settings' topic for more information about customizing the maximum hop count.
  2. Choose hop type.
    Type of hop
    The type of graph traversal used. The options are:
    Host to host hop type
    This type generates a view showing host to host connections.
    Element to element hop type (default)
    This type performs the traversal using all element types in the graph.
    When a topology is viewed without a hop type defined, the element to element default view is displayed.
    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 'h2h', 'e2e', or 'e2h' and can therefore be shared via direct-launch URL string using the URL parameter, (for example hopType=e2e).
    See Topology rendering for more information about changing the default hop type.
  3. 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.
  4. 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)
  1. 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 (which is usually the `noi` instance; you can find the instance name using the oc get noi 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.
  2. 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
  3. 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.