Moogsoft Docs

getSituationTopology

A Graze API GET request that returns a JSON object in NetJSON format that represents the nodes affected by the Situation.

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.

context

Number

No

Number, between 0 and 4, of contextual hops from the nodes directly affected within the Situation to other nodes to be included in the returned object. See Vertex Entropy for more information on contextual hops.

0 = only nodes directly affected by the Situation. Default.

4 = nodes that are up to four hops away from the nodes directly affected by the Situation.

properties

List of strings

No

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.

  • service: Service affected by the node.

  • context: Number of contextual hops between this node and a node directly affected by the Situation. A context of 0 means that the node is directly affected.

  • description: Description of the node.

  • vertex_entropy: Vertex Entropy of the node.

field_name

String

No

Attribute of the alert that defines the node. The default is the alert 'source' but you can specify any valid alert field, including custom_info attributes. For example, field_name=custom_info.eventDetails.line.

Response

Endpoint getSituationTopology returns the following response:

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

Name

Type

Description

links

Integer

List of links associated with the Situation.

links.source

String

Source node of the link.

links.target

String

Target node of the link.

nodes

Array

Array of nodes associated with the Situation and their properties. The nodes included depends on the setting of the request property context.

nodes.id

String

Node ID.

nodes.properties

Array

Object containing the properties requested.

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

API update behavior

The behavior of this endpoint depends on whether the relevant Situation is open, closed and still in the active database, or closed and archived to the historic database. This endpoint updates the Situation as follows:

See API Update Behavior for more information on Situation statuses.

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. The returned object is to contain the properties of severity, Vertex Entropy, Probable Root Cause (PRC), service, and description.

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

The successful response returns the following topology information for this Situation. The response always returns the node names in lower case. 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,
                "service": "",
                "context": 0,
                "description": "",
                "vertex_entropy": 0.1794592472207979
            }
        },
        {
            "id": "host2736",
            "properties": {
                "severity": 4,
                "prc": 0.42722191049803876,
                "service": "",
                "context": 0,
                "description": "",
                "vertex_entropy": 0.08976540495989357
            }
        },
        {
            "id": "host2728",
            "properties": {
                "severity": 3,
                "prc": 0.007672752075071621,
                "service": "",
                "context": 0,
                "description": "",
                "vertex_entropy": 0.1794592472207979
            }
        },
        {
            "id": "host2827",
            "properties": {
                "severity": 5,
                "prc": 0.4262762946261391,
                "service": "",
                "context": 0,
                "description": "",
                "vertex_entropy": 0.05343516483103129
            }
        },
        {
            "id": "host2801",
            "properties": {
                "severity": 5,
                "prc": 0.42722511225514104,
                "service": "",
                "context": 0,
                "description": "",
                "vertex_entropy": 0.23927899629439717
            }
        },
        {
            "id": "host2800",
            "properties": {
                "severity": 5,
                "prc": 0.4269879766269776,
                "service": "",
                "context": 0,
                "description": "",
                "vertex_entropy": 0.05343516483103129
            }
        },
        {
            "id": "host1156",
            "properties": {
                "severity": null,
                "prc": null,
                "service": "",
                "context": 1,
                "description": "",
                "vertex_entropy": 0.05343516483103129
            }
        }
    ]
}