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

Yes

properties

Array of Strings

Yes

field_name

String

Yes

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 alert or Situation is open, closed and still in the active database, or closed and archived to the historic database. This endpoint updates the alert or 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
            }
        }
    ]
}
In this section: