Send health data over HTTP

Search…
StackState version 4.4
Overview
StackState can synchronize health information from your own data sources either via HTTP or the StackState CLI.
StackState Receiver API
The StackState Receiver API accepts health data next to telemetry and topology in a common JSON object. By default, the receiver API is hosted at:
Kubernetes
Linux
1
https://<baseUrl>/receiver/stsAgent/intake?api_key=<API_KEY>
Copied!
Both the baseUrl and API_KEY are set during StackState installation, for details see Kubernetes install - configuration parameters.
1
https://<baseUrl>:<receiverPort>/stsAgent/intake?api_key=<API_KEY>
Copied!
Both the baseUrl and API_KEY are set during StackState installation, for details see Linux install - configuration parameters.
Common JSON object
Health is sent to the receiver API via HTTP POST and has a common JSON object for all messages.
1
{
2
  "collection_timestamp": 1548855554, // the epoch timestamp for the collection
3
  "events": {}, // see the section on "events", below
4
  "internalHostname": "localdocker.test", // the host that is sending this data
5
  "metrics": [], // see the section on "metrics", below
6
  "service_checks": [],
7
  "topologies": [], // used for sending topology data
8
  "health" // used for sending health data
9
}
Copied!
JSON property: "health"
Health can be sent to the StackState Receiver API using the "health" property of the common JSON object.
Example health JSON
1
[
2
    {
3
      "start_snapshot": {
4
        "repeat_interval_s": 50
5
        //"expiry_interval_s": 200 Optional
6
      },
7
      "stop_snapshot": {},
8
      "stream": {
9
        "urn": "urn:health:sourceId:streamId"
10
        //"sub_stream_id": "subStreamId" Optional
11
      },
12
      "check_states": [
13
        {
14
          "checkStateId": "checkStateId1",
15
          "message": "Server Running out of disk space",
16
          "health": "Deviating",
17
          "topologyElementIdentifier": "server-1",
18
          "name": "Disk Usage"
19
        {
20
          "checkStateId": "checkStateId2",
21
          "message": "Provisioning failed. [Learn more](https://www.any-link.com)",
22
          "health": "critical",
23
          "topologyElementIdentifier": "server-2",
24
          "name": "Health Monitor"
25
        }
26
      ]
27
    }
28
]
Copied!
Every health data payload has the following details:
start_snapshot - Optional. A start of a snapshot will be processed before processing the check_states. This enables StackState to diff a stream snapshot with the previously received one and delete check states that are no longer present in the snapshot. It can also carry snapshot metadata:
repeat_interval_s - Time in seconds. The frequency with which the external source will send health data to StackState. Max allowed value is 1800 (30 minutes).
expiry_interval_s - Time in seconds. The time to wait after the last update before an external check is deleted by StackState. Required when using sub streams.
stop_snapshot - Optional. An end of a snapshot will be processed after processing thecheck_states.
stream - Object providing identification regarding which snapshots and check_states belong together. It contains the following fields:
urn - Data source and stream ID encoded as a StackState URN that matches the following convention: urn:health:<sourceId>:<streamId> where <sourceId> is the name if the external data source and <streamId> is a unique identifier for the health data stream.
sub_stream_id - Optional. Identifier for a sub set of the stream health data. When the stream data is distributed and reported by several agents, this allows snapshot lifecycles per sub_stream_id
check_states - A list of check states. Each check state can have the following fields:
checkStateId - Identifier for the check state in the external system
message - Optional. Message to display in StackState UI. Data will be interpreted as markdown allowing to have links to the external system check that generated the external check state.
health - One of the following StackState Health state values: Clear, Deviating, Critical.
topologyElementIdentifier - Used to bind the check state to a StackState topology element.
name - Name of the external check state.
Send health to StackState
Health can be sent in one JSON message via HTTP POST or using the StackState CLI command sts health send. In the example below, a snapshot containing two check states is sent to StackState from a single external monitoring system.
curl
StackState CLI
1
curl -X POST \
2
 'http://<stackstateURL>/stsAgent/intake?api_key=<API_KEY>' \
3
 -H 'Content-Type: application/json' \
4
 -d '{
5
  "collection_timestamp": 1548857167,
6
  "events": {},
7
  "internalHostname": "localdocker.test",
8
  "metrics": [],
9
  "service_checks": [],
10
  "topologies": [],
11
  "health":[
12
  [
13
    {
14
      "start_snapshot": {
15
        "repeat_interval_s": 300
16
      },
17
      "stop_snapshot": {},
18
      "stream": {
19
        "urn": "urn:health:sourceId:streamId"
20
      },
21
      "check_states": [
22
        {
23
          "checkStateId": "checkStateId1",
24
          "message": "Server Running out of disk space",
25
          "health": "Deviating",
26
          "topologyElementIdentifier": "server-1",
27
          "name": "Disk Usage"
28
        {
29
          "checkStateId": "checkStateId2",
30
          "message": "Provisioning failed. [Learn more](https://www.any-link.com)",
31
          "health": "critical",
32
          "topologyElementIdentifier": "server-2",
33
          "name": "Health Monitor"
34
        }
35
      ]
36
    }
37
]
38
}'
Copied!
1
sts health send start urn:health:sourceId:streamId \
2
  --repeat-interval-seconds 300
3
​
4
sts health send check-state urn:health:sourceId:streamId \
5
  checkStateId1 "Disk Usage" "server-1" deviating \
6
  --message "Deviating Server Running out of disk space"
7
​
8
sts health send check-state urn:health:sourceId:streamId \
9
  checkStateId2 "Health Monitor" "server-2" critical \
10
  --message "Provisioning failed. [Learn more](https://www.any-link.com)"
11
​
12
sts health send stop urn:health:sourceId:streamId
Copied!
You can also send health to StackState using the StackState CLI health send command.
See also
​Install the StackState CLI​
​StackState CLI reference​
Health synchronization
Debug health synchronization
Last modified 2mo ago
Copy link
Contents
Overview
StackState Receiver API
Common JSON object
JSON property: "health"
Send health to StackState