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 |
|---|---|---|---|
| String | Yes | A valid |
| 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.
|
| List of strings | No | List of the node properties to be returned. Valid properties are:
|
| 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 |
Response
Endpoint getSituationTopology returns the following response:
Successful requests return an array of JSON objects containing the following:
Name | Type | Description |
|---|---|---|
| Integer | List of links associated with the Situation. |
| String | Source node of the link. |
| String | Target node of the link. |
| Array | Array of nodes associated with the Situation and their properties. The nodes included depends on the setting of the request property |
| String | Node ID. |
| 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.
 |
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
}
}
]
}