Viewing topologies

A topology is a graphical representation of an application (service), or a resource group, or an individual resource. When you render a topology, it displays all of the constituent elements and relationships that make up your topology, and then lets you refine and manipulate the view.

You can use the interactive topology tools to drill into the individual resource details and status, enable a timeline to view changes over time, and more. You can also use this view to triage issues when an incident occurs.

When you view a topology, you can zoom in and out of specific areas of the topology or pan across it in various ways. You can auto-fit the topology into the available display window, draw a mini map, or redraw the entire topology. You can also filter your types of resources that are displayed, or your types of relationships that are rendered.

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 an application or resource group in table format instead.

Severity status

Severity status icons
Icon Severity
Clear icon clear
Indeterminate icon indeterminate
Information icon information
Warning icon warning
Minor icon minor
Major icon major
Critical icon critical

You can manipulate the topology by using a number of tools:

Before you begin

To view a topology, it must be defined first. The following procedure details how to view existing topologies for applications, resource groups and resources.

About this task

You view a topology from the Resource management page.

To view a topology

  1. Log in to the IBM Cloud Pak for AIOps console.

  2. From the main navigation, click Resource management.

    On the Resource management dashboard, applications, resource groups and resources are presented on separate tabs. In addition, the dashboard is divided into 'All applications results' and 'Favorites' sections. You can display favorite applications and resource groups either as cards or in a table. Resources are always displayed in a table, and cannot be designated as favorites.

  3. To view an application, resource group or resource as a topology, click the name. Alternatively, use Search.

    • Search: As you type in a search term, such as a name, tag, entity type or unique Id, a drop-down list is displayed with suggested search terms that exist in the topology service. If you select one of the suggested results, the Search Results page is displayed listing possible resource results that match the selected search term. The Results are listed under separate tabs.

      • If the resource that you are searching for is unique, the resource can be included in the drop-down list of suggestions. If you are confident that the listed suggestion is the resource that you are searching for, you can click the View topology for the closest matching resource icon in the drop-down list to render the topology for the closest matching resource to that suggestion.

      • Optional: If the resource that you are looking for might be deleted, you can select Include deleted resources (unless an administrator disables this feature). When this toggle is enabled, the search results include any deleted resources. Deleted templates or resource groups are not included in any search results. Deleted resources are marked as deleted and include the date and time that they were deleted. If you click View topology, the resource topology is displayed with the history timeline open. The timeline is set to 1 ms before the resource was deleted. When you close the timeline, 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 serch result, the name, type and other properties are displayed. You can expand a search result entry for more details, such as its status and any associated severity levels, or when the resource was previously updated. If a status other than clear exists for a search result, the maximum severity is displayed.

      • Tip: You can perform more complex searches, such as searching with multiple search terms. For more information about advanced query syntax, see the topology query reference topic.

Viewing and modifying the topology presentation

When you view a topology, you can zoom in and out of specific areas of the topology, and pan across it in various ways. You can auto-fit the topology into the available display window, draw a mini map, redraw the entire topology, or filter the types of resources displayed or the types of relationships rendered.

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.

Tip: Click View Legend to open a Help panel that describes the visual elements that are used in the rendering of the topology (such as lines styles, icons, and symbols).

Tip: By default, a topology is displayed in graphical view format. Click the Tabular view button to switch to a table view, or the Map view button to view the topology resources displayed on a map.

Information bar: A bar at the bottom of the topology visualization displays the status of the rendered topology, including a timestamp on the left to indicate the time of the most recent refresh. If two time periods are being compared, both are indicated. Additional information on the right side of the information bar indicates the number of resources that are rendered, and the number of associated relationships. The bar also indicates whether any of the resources or relationships were added or removed since the last refresh, and whether a filter is applied.

When changes are made to a topology, the following conventions are used to identify the changes:

  • Deleted resources

    A minus icon indicates that a resource was deleted since the topology was last rendered. This icon displays when a topology is updated, and within the history views.

  • Added

    A purple plus icon indicates that a resource was added since the topology was last rendered. This icon displays when a topology is updated, and within the history views.

  • Added (neighbors)

    A blue asterisk icon shows that a resource was added by using the 'get neighbors' function.

You can manipulate the topology by using a number of tools. Depending on whether you are viewing the topology for a resource, resource group or an application, the tools that are available can be different.

Tabular view

If you click Tabular view to display the topology in table format, it lists the Name, Type, Resource alerts, Tags and Business criticality (if defined) for each resource. The (collapsable) Incidents panel on the right of the topology is open by default.

  • Tip: If you 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.

  • You can also dynamically filter the table by creating a filter, using a predefined filter or by typing names, types or tags into the Search field.

    Note: Elements that are not displayed when viewing resources in table format, such as relationship types, are not available for filtering.

  • You can display resources at a historical point in the past by clicking Choose a historical time on the toolbar. From the Choose a historical time dialog, select a new moment in time up to the data retention limit set for your system (the default is thirty days in the past). If you return to the current time, the data is refreshed.

    Tip: If you switch back from a tabular to a topology view, the time pin has moved according to the historical date you have selected.

  • You can click Resource details on the overflow menu to open the Resource Details window.

  • You can perform a number of additional context-dependent activities from the overflow menu of each displayed item in the table, such as viewing comments, showing the item in a map, assigning business criticality, opening it in the topology viewer, or building a template.

Tip: You can share a link to the application (or resource group) in tabular format with other users.

Troubleshooting: When moving between a tabular and a graphical view several times while also using the timeline toggle, the display may freeze. To avoid this issue, do not disable the timeline while using historic mode in the tabular view. If the issue does occur, refresh the page to reset.

Tabular view overflow menu

The overflow menu (the three dots next to each table entry) gives you access to the following functionality:

  • Click Resource details on the overflow menu.

    The Resource details page has a number of tabs.

    Properties: Displays a window that shows all the current stored properties for the specified resource in tabular and JSON format. If a property has been excluded from view by an administrator, it is only visible in JSON format. The resource name is an active link that opens a topology view of the resource in context. Toggle the Show JSON switch On or Off to display the properties in JSON format.

    Alerts: Displays a dialog that shows the time-stamped statuses related to the specified resource in table format.

    Data origin: Displays the point of origin of the resource data, such as a specific observer job. If you have the appropriate user permission, such as the administrator role, the observer job name is an active link, which opens the observer job page from where you can re-run the job, view its history, or edit the job.

    Related applications: Displays all related applications as active links, which open the service topologies in new windows. Also lists the group type, number of groups, status, and tags.

    Related resource groups: Displays all related resource groups as active links, which open the resource group topologies in new windows. Also lists the resource type, number of resources, status, and tags.

    Neighbor resources: Displays all neighboring resources in a table. Click a resource name to open the details page for the resource.

    Location: Opens a map in which the resource is geo-located.

    Structure view: Displays all resources that are part of a host or parent resource.

  • Click Resource alerts on the overflow menu to access the Resource details page for the selected resource with the Alerts tab selected.

  • Click View related incidents on the overflow menu to display related incidents for the selected resource on the Incidents panel.

  • Click Comments on the overflow menu to access the commenting functionality.

    When selected, this displays any comments recorded against the resource. By default, resource comments are displayed by date in ascending order. You can sort them in the following way:

    • Oldest first
    • Newest first
    • User Id (A to Z)
    • User Id (Z to A)

    Users with the appropriate permissions can view or add new comments.

  • Click Assign business criticality on the overflow menu to define business criticalities for the selected resource.

  • Click Build a template on the overflow menu to opens the Create a new template dialog, from where you can create a new resource group template.

  • Click Compare resources on the overflow menu to select a second resource for side-by-side comparison in a table.

  • Click Open in Topology viewer on the overflow menu to open a resource as a topology view.

    From here, you can drill into individual resource details and status, enable a timeline to view changes over time, and more. You can also use this view to triage issues.

  • Click Show on map on the overflow menu to display the resource on a map.

Map view

The map view displays the topology elements on a map. For more information, see Viewing resources on a map.

Vizualisation tools

A number of tools and functions let you manipulate the topology presentation.

Refresh rate

You can expand the Refresh rate drop-down field to select your preferred refresh rate or to pause the option. This rate determines when the topology page auto-updates to search for and include new changes.

You can pause the topology data refresh, or specify the following values: 10 seconds, 30 seconds (default), one minute, or five minutes.

Refresh

You can click Refresh to manually refresh the topology data, which also clears all user-specific session data.

About this application

Opening this twisty displays a summary for the selected application topology, such as the date and time it was created, the associated groups and whether any have been added, any tags and business criticalities associated with it, and the date and time it was last updated.

About this resource group

Opening this twisty displays a summary for the selected resource group topology, such as the date and time it was created, the associated applications and whether any have been added, any tags associated with it, and the date and time it was last updated.

Filters

You can either use a predefined filter by selecting it from the Select a filter drop-down, or create a new one by clicking the Open filter icon and defining new filter conditions.

For more information, see the searching and filtering topic.

Settings

From this menu, you can select to open pages for managing the following types of settings:

  • Topology configuration

    You can configure the following topology elements to change how users can visualize, manipulate, and use topologies:

    • Advanced settings

      Control how the topology user interface works for all users.

    • Topology tools

      Create tools that can be accessed from within the topology's context menu.

    • Resource types

      Customize the style of your resources.

    • Relationship types

      Customize the style and label for relationships.

    • Custom icons

      Add custom icons for resources that are displayed in the topology.

    • Rules

      Define automated processing rules for your topology data.

    For more information, see Configuring topology elements.

  • Create exact template

    Opens the Using resource group templates page already populated with the current view elements including the preview pane to the right of the Template builder. From here, you can create a new exact resource group template.

    Restriction: While viewing topologies, you can only create exact templates based on element-to-element topologies. The Create exact template option will not appear in the Settings drop-down for other views.

    Tip: As a further refinement, you can adjust your layout by manually positioning the resources in the topology, and this layout is then replicated when you generate a resource group from any exact template that you build from this topology.

  • User preferences

    You can set your personal preferences for how topologies are rendered. The settings that can personalize are grouped into the following categories:

    • Updates

      These settings determine how and how often topologies are automatically updated.

    • Layout

      These settings determine the default presentation of topologies.

    • Miscellaneous

      Other settings, such as displaying messages, screen reader support, and troubleshooting.

    For more information, see User preferences.

Sharing options

You can share a topology either by obtaining a direct URL linking to the topology view, or by exporting a view of the topology as an image. To select a sharing option, click the Sharing options icon and then click your preferred option:

  • Obtain direct URL

    This option displays the Direct topology URL dialog. This dialog includes a displayed URL, which captures the current topology configuration, including the layout type. The layout orientation is not tracked.

    Click the Copy direct URL to clipboard icon to the right of the URL to copy the direct-launch URL string for accessing the topology view. You can then share the URL with a colleague or use the URL to directly access the topology later.

    Then, click Close.

  • Export as PNG

    Click this option to export a snapshot of the current topology in PNG format. The snapshot is automatically downloaded based on your browser download settings. By default, the file is saved as topology.png. You can now share the image as required.

  • Export as SVG

    Click this option to export a snapshot of the current topology in SVG format. The snapshot is automatically downloaded based on your browser download settings. By default, the file is saved as topology.svg. You can now share the image as required.

Number of hops (resource topologies only)

The number of relationship hops to visualize from the seed resource. You can define the number of relationship hops to be performed, which can be from zero to four, unless this setting has been customized. The default is set at 'one'.

For more information about configuring the maximum hop count, see the Configuring advanced topology settings.

Type of hop (resource topologies only)

The type of graph traversal used. The options are:

  • Element to element (default)

    This type performs the traversal by using all element types in the graph. If no hop type has been defined, a topology is rendered using the element to element hop type as default.

  • Host to host

    This type generates a view showing host to host connections.

  • Element to host

    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 allows you to set h2h for host to host, e2e for element to element, or e2h for element to host.

Render (resource topologies only)

This button causes the topology visualization to run to update a topology based on any changes to the topology or the navigation toolbar settings. This process integrates any new resources into the topology. Choosing this option recalculates the topology layout based on your current display settings, which can adjust the displayed topology significantly. Once the rendering is complete, the topology refreshes on a 30-second interval by default. You can pause the auto-update refresh, or select a custom interval.

Tip: The IBM Cloud Pak for AIOps console can time out when a large amount of data is being retrieved for rendering. For more information about how to address this issue, see Rendering (visualizing) a topology.

Delta

You can toggle the Delta button to show how your selected topology changes between two points in time.

Timeline

Use the Timeline toggle to open and close the History toolbar below the topology. This view shows how the selected resource changed over time. For more information about the details and how you can use this view, see Viewing topology history.

View legend

Click View Legend to open a Help panel that describes the visual elements that are used in the rendering of the topology, such as symbols, icons and line styles.

Topology view tools

A list of tool icons is displayed near the top right hand side. You can hover over some icons to display a submenu.

  • Select tool

    Use this icon to select individual resources by using a mouse click, or to select groups of resources by creating a selection area (using click-and-drag).

  • Pan tool

    Use this icon to pan across the topology by using click-and-drag on a blank area of the visualization panel.

  • Zoom Select tool

    Use this icon to zoom in on an area of the topology by using click-and-drag.

  • Zoom In

    Use this icon to zoom in on the displayed topology.

  • Zoom Out

    Use this icon to zoom out of the displayed topology.

  • Zoom Fit

    Use this icon to fit the entire topology in the current view panel.

  • Overview

    Use this icon to create the overview mini map in the lower right corner. The mini map provides an overview of the entire topology while you zoom in or out of the main topology. The mini map displays a red rectangle to represent the current topology view. Note: In some browsers, the use of the mini map might cause performance issues when displaying large topologies.

  • Layout

    Use this icon to recalculate, and then render the topology layout again. You can choose from a number of layout types and orientations.

    • Layout 1

      A layout that displays all resources in a topology without applying a specific layout structure.

    • Layout 2

      A circular layout that is useful when you want to arrange a number of entities by type in a circular pattern.

    • Layout 3

      A grouped layout is useful when you have many linked entities, as it helps you visualize the entities to which a number of other entities are linked. This layout helps to identify resource groups of interconnected entities and the relationships between them.

    • Layout 4

      A hierarchical layout that is useful for topologies that contain hierarchical structures, as it shows how key vertices relate to others with peers in the topology being aligned.

    • Layout 5

      A peacock layout is useful when you have many interlinked vertices, which resource group the other linked vertices.

    • Layout 6

      A system board rank layout is useful when you want to view how the topology relates to a vertex in terms of its rank, and also how vertices are layered relative to one another.

    • Layout 7

      A rank layout is useful when you want to see how a selected vertex and the vertices that are immediately related to that rank relative to the remainder of the topology (up to the specified number of hops). The root selection is automatic.

      For example, vertices with high degrees of connectivity outrank lower degrees of connectivity. This layout ranks the topology automatically around the specified seed vertex.

    • Layout 8

      A root rank layout similar to layout 7, except that it treats the selected vertex as the root. This layout is useful when you want to treat a selected vertex as the root of the tree, with others being ranked below it.

Interacting with a topology

A displayed topology consists of resource nodes and the relationship links connecting the resources. You can interact with these nodes and links. You can use the topology to also view critical issues and interact with the related resource nodes to troubleshoot the issue.

You can select, move, and view more options for managing nodes and the associated resources.

  • Select a node

    Selecting a node highlights that node, and emphasizes its first-order connections by fading all other resources.

  • Move a node

    Click and drag a node to move it.

  • View the context menu

    Right-click a node to view the context menu. From this menu you can select more options for viewing details and managing the topology. For the included options, see Context menu

Context menu

You open the context menu by using the right-click function. The context menu provides access to the resource-specific actions that you can perform.

For resource entities, you can access the following context menu items:

Resource details

Note: The details dashboard is accessed either from the topology context menu or the Resource management dashboard. Some items may be unavailable.

If opened from the Resource management tool in the UI, the resource name is an active link that opens a topology view of the resource in context, provided you have the correct user permissions (the waiops_manage_integrations or waiops_view_integrations permissions).

If a map has been defined, the Map link next to the resource name opens the Resource map view. When selected while viewing a topology history with delta mode On, the Resource details window displays the properties of the resource at both the reference time and at the delta time. 'Related services' and 'Related resource groups' are only displayed when not in historical mode.

Properties tab: Displays all the current stored properties for the specified resource in tabular and JSON format. If a property has been excluded from view by an administrator, it is removed from the tabular view, but remains visible in JSON format.

Tip: Toggle the Show JSON switch On or Off to display the properties in JSON format.

Alerts tab: Displays a dialog that shows the time-stamped statuses related to the specified resource in table format. The Severity and Time columns can be sorted, and the moment (that is, the historical time point) that Resource status was selected is also time-stamped.

You can use the Show active only toggle to remove inactive statuses. In addition, if any status tools have been defined, the status tool selector (three dots) is displayed next to the resource's statuses.

Click the status tool selector to display a list of any status tools that have been defined, and then click the specific tool to run it. Status tools are only displayed for the states that were specified when the tools were defined. The severity of a status ranges from 'clear' (white tick on a green square) to 'critical' (white cross on a red circle). For the list of status, see the Severity status table.

Tip: If statuses related to a specific resource are available, the resource is marked with an icon depicting the status severity level, and the Resource status tab will appear on the Resource details window, accessible through the resource context menu.

Data origin tab: Displays the point of origin of the resource data, such as a specific observer job. If you have the appropriate user permission, such as the administrator role, the observer job name is an active link, which opens the observer job page from where you can rerun the job, view its history, or edit the job.

Related applications tab: Displays all related applications as active links, which open the application topologies in new windows. Also lists the group type, number of groups, status, and tags.

Related resource groups tab: Displays all related resource groups as active links, which open the resource group topologies in new windows. Also lists the resource type, number of resources, status, and tags.

Neighbor resources tab: Displays all neigboring resources and their names, relationships and types, alerts (max severity only) and tags.

Location tab: Opens a map in which the resource is geo-located. Zoom functions are enabled, though the map is limited to the More details dialog. To open the full map, use the Map link next to the resource name.

Structure view tab: Displays all resources that are part of a host or parent resource (such as a device), which are linked together in a relationship via the 'partOf' edge regardless of their position; that is, it displays linked resources even if they are several hops removed from one another or from the host (parent) resource.

The Structure view tab displays all the current stored properties for a selected resource on the right in tabular and JSON format (as for the properties tab), with an additional breadcrumb above the details showing its distance from its parent resource.

On the left, a resource tree is shown, expanded to the resource from which the structure view was opened, with the parent resource at the highest level. The highest severity resource status is shown next to the name, although if a status is shown in parenthesis, the status applies to a resource nested at a lower level.

You can click on a resource name to open a topology view of the resource and its parent resource. When you display a parent resource, all resource linked to it via the partOf edge are also depicted. If you activate the Problem view toggle, all resources with no reported issues are filtered out.

Comments

When selected, this displays any comments that are recorded against the resource.

By default, resource comments are displayed by date in ascending order. You can sort them in the following way:

  • Oldest first
  • Newest first
  • User ID (A to Z)
  • User ID (Z to A)

To add a comment, enter text into the New Comment field, and then click Add Comment to save.

Assign criticality

Business criticality sets the priority level for a resource (or application, or resource group).

To assign a priority, select a definition from the Business criticality drop-down, then click Save.

Remember: Business criticality definitions must be created by an administrator user before you can assign them to a resource. This is described in the Defining business criticality topic.

Compare resources

You can select two resources and their properties for side-by-side comparison, with different values highlighted.

In Resource management, select the Resources tab, and next to a resource to be compared (Resource A), click Compare resources from the overflow menu.

The Compare resources page opens with the standard details for Resource A displayed in a table.

Note: Alternatively, you can launch the Compare resources page from a specific resource's context (right-click) menu in the topology viewer.

Use the *Search field to identify and select a second resource (Resource B) for comparison.

The table displays the properties for Resource A and Resource B in adjacent table columns.

  • Different property values are highlighted.
  • If a historical time point was selected, the properties from that time point are displayed.

Build a template

Select the type of template to use to group resources

  • Dynamic template

    This template automatically finds and updates multiple resource groups based on your criteria and how your services and infrastructure change.

  • Tag based template

    This template creates and updates a single resource group containing the resources that have a specified set of tags.

  • Exact template

For more information, see Resource group templates.

Get neighbors

When selected, a menu opens to display the resource types of all neighboring resources. Each resource type lists the number of resources of that type, and the maximum severity associated with each type.

You can click the menu option Choose specific to open a dialog to select specific resources that you want to add to the current topology visualization. You can also choose to include all neighboring resources. When you select a resource, a confirmation option displays for you to either Add neighbors or Cancel. After you select Add neighbors, Undo is available for you to undo the last add neighbor request.

Selecting Get Neighbors overrides any existing filters.

Follow relationship

When selected, opens a menu that displays all adjacent relationship types. Each relationship type lists the number of relationships of that type, and the maximum severity associated with each type. You can choose to follow all relationships, or only the neighbors of a specific type.

Show last change in timeline

When selected, this displays the history timeline, depicting the most recent change made to the resource.

Show first change in timeline

When selected, this displays the history timeline, depicting the first change made to the resource.

Find path

When you click the Path tool, the Find path dialog opens. From this dialog, you can define criteria for finding the shortest path between the currently selected resource and a second specified resource within the topology.

Within the Path definition section, you need to specify the start and end points (resources) for the path:

  • Path start resource

    Identifies the selected resource from the topology.

  • Path end resource

    Search for the resource that you want to use with the starting resource for calculating the shortest path.

Within the Filters section, specify the resource types and relationship types to include or exclude from the calculated path topology.

  • Filter mode

    Choose to Exclude or Include the resource or relationship types from the path.

  • Resource types

    Search for or browse the drop-down list of resource types and select any types to be included or excluded. The list includes all defined types.

  • Relationship types

    Search for or browse the drop-down list of relationship types and select any types to be included or excluded. The list includes all defined types.

  • Maximum number of hops

    The maximum number of hops you can permit when calculating the path. You can set the value at 1-30 hops. The default is 30 hops.

When you have completed your selections, click Find path. A browser tab for the Topology viewer tab opens and is labeled Path topology. The shortest path between the start and end resources is calculated and is shown on this Path topology tab. This view shows up to a maximum of five paths. The time taken to calculate the shortest path depends on the complexity of the links between the selected resources. You can continue to work with the current topology while the path is being calculated and the associated topology rendered.

Within the path topology, the start and end resources are highlighted initially. When you hover over a link between any resources, all the paths that include those resources are highlighted.

If needed, you can further filter the displayed topology by using the Filter toolbar.

Recenter View

When selected, the displayed topology is updated from the specified seed resource to include any changes.