Moogsoft Docs

Graph Topology

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. See the Wikipedia entry for more information.

Topology data for the Graph Topology module, which is imported into Moogsoft AIOps using the Topology Builder utility, is in a CSV 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

The data above represents the following topology, with nodes named  host_<value>  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, define a new global object  topo  at the top of a JavaScript Moobot file:

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

Reference Guide

The Graph Topology module uses the following methods:

Loads the topology into the Graph Topology module and reports 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|+

isConnected

Checks 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, run:

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

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

This 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|+

connected

Checks 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, run:

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

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

This 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|+

distance

Checks the distance (shortest path) between two specified nodes, with an optional specified maximum distance (radius). Use the radius argument 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 The maximum Distance to return a result for. Optional.

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, run:

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

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

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

numberOfConnections

Counts 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, run:

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

This 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