getSituationTopology

A Graze API endpoint that returns the topology details for a specified Situation and topology. The request returns a JSON object that lists the links and nodes affected by the Situation in a specified topology. It also returns the alert matching attributes for the nodes in the topology.

Back to Graze API EndPoint Reference.

Request arguments

Endpoint getSituationTopology takes the following request arguments:

Name

Type

Required

Description

auth_token

String

Yes

A valid auth_token returned from the authenticate request. See the authenticate endpoint for more information.

sitn_id

Number

Yes

Situation ID.

topology_name

String

Yes

Name of the topology for which to return the Situation's link, node and alert matching attribute details. A Situation can impact nodes in multiple topologies.

context

Number

Yes

properties

Array of Strings

Yes

List of the node properties to be returned. Valid properties are:

  • severity: Severity of the node.

  • prc: Whether this node is the probable root cause of the alert.

  • description: Description of the node.

  • vertex_entropy: Vertex Entropy of the node. See Vertex Entropy for more information.

Response

Endpoint getSituationTopology returns the following response:

Successful requests return an array of JSON objects containing the following:

Name

Type

Description

links

Array of strings

One or more links associated with the Situation, including the following properties:

  • source: Source node of the link.

  • target: Target node of the link.

Note that links in Moogsoft Enterprise are bidirections.

nodes

Array of strings

One or more nodes associated with the Situation and their IDs and properties. The context request property determines which nodes are included.

alertMatchingAttributes

Array of strings

The alert fields that specify the topology nodes from which the alerts were generated.

See http://netjson.org/ for more information on the topology data format.

Examples

The following examples demonstrate typical use of endpoint getSituationTopology:

Request example

The following topology diagram shows the nodes affected by Situation ID 14, with a context of 1. In this example, each node represents a host in a network and the Situation represents a network outage. It shows six nodes directly affected by the Situation, their color depending on their severity, and one node which is one hop away, shown in gray.

29962200.png

The following cURL request demonstrates a request to return nodes affected by the Situation and nodes that are one hop away in the "network" topology. The returned object contain the properties of severity, Vertex Entropy, Probable Root Cause (PRC), and description.

curl -G -u graze:graze -k -v "https://localhost/graze/v1/getSituationTopology" \
--data-urlencode "sitn_id=14" \
"topology_name=network" \
"context=1" \
"properties"= [ "severity","vertex_entropy","prc","description" ]

Response example

The successful response returns the following topology information for this Situation. Note that there is no PRC value for the node that is not directly affected by the Situation. In this example, consider investigating node "host2835" as the cause of the Situation because it has a high severity and a high PRC.

{
    "links": 
    [
        {
            "source": "host2728",
            "target": "host2736"
        },
        {
            "source": "host2728",
            "target": "host1156"
        },
        {
            "source": "host2835",
            "target": "host2728"
        },
        {
            "source": "host2801",
            "target": "host2827"
        },
        {
            "source": "host2800",
            "target": "host2801"
        },
        {
            "source": "host2801",
            "target": "host2835"
        },
        {
            "source": "host2835",
            "target": "host2736"
        }
    ],
    "nodes": 
    [
        {
            "id": "host2835",
            "properties": {
                "severity": 5,
                "prc": 0.9862626716344282,
                "context": 0,
                "description": "node1",
                "vertex_entropy": 0.1794592472207979
                }
            },
        {
            "id": "host2736",
            "properties": {
                "severity": 4,
                "prc": 0.42722191049803876,
                "context": 0,
                "description": "node2",
                "vertex_entropy": 0.08976540495989357
                }
            },
        {
            "id": "host2728",
            "properties": {
                "severity": 3,
                "prc": 0.007672752075071621,
                "context": 0,
                "description": "node3",
                "vertex_entropy": 0.1794592472207979
            }
        },
        {
            "id": "host2827",
            "properties": {
                "severity": 5,
                "prc": 0.4262762946261391,
                "context": 0,
                "description": "node4",
                "vertex_entropy": 0.05343516483103129
            }
       },
       {
           "id": "host2801",
           "properties": {
               "severity": 5,
               "prc": 0.42722511225514104,
               "context": 0,
               "description": "node5",
               "vertex_entropy": 0.23927899629439717
           }
       },
       {
           "id": "host2800",
           "properties": {
               "severity": 5,
               "prc": 0.4269879766269776,
               "context": 0,
               "description": "node6",
               "vertex_entropy": 0.05343516483103129
           }
       },
       {
           "id": "host1156",
           "properties": {
               "severity": null,
               "prc": null,
               "context": 1,
               "description": "node7",
               "vertex_entropy": 0.05343516483103129
           }
       }
    ],
    "alertMatchingAttributes": ["source"]
}
In this section: