Graph Topology

Note

If you would like to use the topology feature, contact Moogsoft support for guidance.

The Graph Topology module uses an alternative clustering technique to refine accuracy and reliability, by using a shortest path measurement for clustering in Cookbook Moobot recipes.

In Moogsoft AIOps, Situations can be generated by clustering events based upon the proximity in a network of the source devices sending the events. To do this, the source devices and their weighted connections are mapped in a topology.

Source devices in a network are represented as points in the topology called 'nodes'. Connections between the source devices are represented in the topology as 'edges'. Edges can be weighted to represent the connection length. If no weight is defined for an edge, the default value is 1. The number of connections on a node is called the 'degree' of the node.

Distance

'Distance' is the shortest path between two nodes via the weighted edges (using Dijkstra's algorithm. More information from Wikipedia).

Topology data for the Graph Topology module, which is imported into Moogsoft AIOps using the topology_builder utility, is in a CSV (comma separated value) file. Each edge defined in the CSV file is treated as representing a bi-directional connection between the specified nodes.

Each entry in the file names the two nodes that are connected, and (optionally) the weighted edge number, in the following format:

<first node>, <second node>, <weighted edge number>

If no <weighted edge number> is included, the default value of 1 is used.

Example CSV file:

host_a3,host_a1,2
host_a3,host_a2,3
host_a4,host_a1,6
host_a5,host_a1,2
host_a5,host_a4,2
host_a6,host_a1,7
host_a6,host_a2,8
host_a6,host_a4,4
host_a6,host_a5,7
host_b3,host_b2,6
host_b4,host_b1,3
host_b4,host_b3,8
host_b5,host_b3,5
host_b5,host_b4,3
host_b6,host_b5,5

Note

This data is used in the code examples below

The data above represents the following topology, with nodes named 'host_...' and the weighted edges (see section on distances above) between them:

The Graph Topology module is available to load into any standard MooBot.

To use, at the top of a MooBot js file, define a new global variable topo to load the Graph Topology module:

var topo = MooBot.loadModule('GraphTopo');

Reference Guide

The Graph Topology module uses the following methods:

Load the topology into the Graph Topology module and report success or failure. A failure to load may be because the topology_builder utility has not imported the topology data CSV file.

Request Argument

None.

Return Parameter

Type

Description

Boolean

true = topology loaded successfully, false = topology failed to load

Example

Request example to load a topology:

var ret = topo.loadTopology();
logger.warning("loadTopology -> " + ret);

Response if the topology loaded successfully:

WARN : ... [CLogModule.java]:99 +|loadTopology -> true|+

topo.isConnected()

Check if a specified node is part of the topology.

Request Argument

Name

Type

Description

host

String

The name of the node being checked

Return Parameter

Type

Description

Boolean

true = node in topology, false = node not in topology

Examples

Using the example topology data above, running:

ret = topo.isConnected("host_a3");
logger.warning("isConnected 1 -> " + ret);

ret = topo.isConnected("does_not_exist");
logger.warning("isConnected 2 -> " + ret);

...returns the output below. The first node (host_a3) is in the topology, the second node (does_not_exist) is not:

WARN : ... [CLogModule.java]:99 +|isConnected 1 -> true|+

WARN : ... [CLogModule.java]:99 +|isConnected 2 -> false|+

topo.connected()

Check if there's a path between two specified nodes.

Request Arguments

Name

Type

Description

host1

String

The name of the first node being checked

host2

String

The name of the second node being checked

Return Parameter

Type

Description

Boolean

true = path between nodes exists, false = no path between nodes

Examples

Using the example topology data above, running:

ret = topo.connected("host_a1", "host_a2");
logger.warning("connected 1 -> " + ret);

ret = topo.connected("host_a1", "host_b2");
logger.warning("connected 2 -> " + ret);

...returns the output below. The first path (between host_a1 and host_a2) exists, second path (between host_a1 and host_b2) does not:

WARN : ... [CLogModule.java]:99 +|connected 1 -> true|+

WARN : ... [CLogModule.java]:99 +|connected 2 -> false|+

topo.distance()

Check the Distance (shortest path) between two specified nodes, with an optional specified maximum Distance (radius).

Use radius to reduce the calculation time if you are not interested in long distances.

Request Arguments

Name

Type

Description

host1

String

The name of the first node being checked

host2

String

The name of the second node being checked

radius

number

Optional.

The maximum Distance to return a result for

Return Parameter

Type

Description

Number

The Distance between the two nodes. Returns -1 if:

• a node is not in the topology or the two nodes are not directly or indirectly connected

• the Distance is larger than the (optionally) supplied radius

Example 1

Using the example topology data above, run the following:

ret = topo.distance("host_a5", "host_a6");
logger.warning("distance 1 -> " + ret);

No radius is specified, so there is no maximum limit on the Distance (shortest path) returned.

All connections (direct and indirect) between nodes host_a5 and host_a6 are as follows:

Edge value

Connection from host_a6 to host_a5

7

Direct

6

via host_a4 (2+4)

9

via host_a1 (2+7)

12

via host_a4 then host_a1 (4+6+2)

15

via host_a1 then host_a4 (7+6+2)

15

via host_a2 and host_a3, then host_a1 (8+3+2+2)

21

via host_a2 and host_a3, then host_a1 and host_a4 (8+3+2+6+2

WARN : ... [CLogModule.java]:99 +|distance 1 -> 6|+

The Distance (shortest path) between the nodes host_a5 and host_a6 is 6, and the output below is returned:

Note

Although the direct connection between nodes host_a5 and host_a6 has an edge (weighted connection) of 7, the shortest path is the indirect connection via node host_a4, with a Distance of 6 (2 + 4)

Example 2

Using the example topology data above, run the following:

ret = topo.distance("host_b2", "host_b6", 8);
logger.warning("distance 2 -> " + ret);

The radius is specified as 8. All connections (direct and indirect) between nodes host_b2 and host_b6 are as follows:

Edge value

Connection from host_2 to host_b6

16

via host_b3 then host_b5 (6+5+5)

22

via host_b3, then host_b4 then host_b5 (6+8+3+5)

None of the connections have a path of 8 or less, so the result is -1, and the output below is returned:

WARN : ... [CLogModule.java]:99 +|distance 2 -> -1|+

Example 3

Using the example topology data above, running:

ret = topo.distance("host_a5", "host_b5");
logger.warning("distance 3 -> " + ret);

...returns the output below. The two nodes are not connected directly or indirectly, so -1 is returned:

WARN : ... [CLogModule.java]:99 +|distance 3 -> -1|+

topo.numberOfConnections()

Count the degree (number of connections) from a specified node.

Request Argument

Name

Type

Description

host

String

The name of the node being checked.

Return Parameter

Type

Description

Number

The node's degree. Returns 0 if the node does not exist or has no connection.

Example

Using the example topology data above, running:

ret = topo.numberOfConnections("host_b3");
logger.warning("numberOfConnections -> " + ret);

...returns the output below. The degree of node host_b3 is 3:

WARN : ... [CLogModule.java]:99 +|numberOfConnections -> 3|+

Optional parameter: Double weight (default value=1.0)

These will add a new node to a topology/graph both in memory and in the database.

Behavior:

• if unspecified, weight will have default value 1.0

• any new nodes will saved in memory and db

• new connection will be saved in memory and db

GraphTopo:

• won't work if there already is such edge