Transactional Increments JSON
StackState Self-hosted v5.0.x
This page describes StackState version 5.0.
This page describes the exact JSON messages that can be sent for the health synchronization Transactional Increments consistency model.
Health can be sent to the StackState Receiver API using the
"health" property of the common JSON object.Example health `transactional_increments` JSON
"apiKey":"your api key",
"collection_timestamp":1585818978,
"internalHostname":"lnx-343242.srv.stackstate.com",
"events":{},
"metrics":[],
"service_checks":[],
"health":[
{
"consistency_model": "TRANSACTIONAL_INCREMENTS",
"increment": {
"checkpoint": {
"offset": 5,
"batch_index": 102
},
"previous_checkpoint": {
"offset": 5,
"batch_index": 100
}
},
"stream": {
"urn": "urn:health:sourceId:streamId"
//"sub_stream_id": "subStreamId" Optional
},
"check_states": [
{
"checkStateId": "checkStateId1",
"message": "Server Running out of disk space",
"health": "Deviating",
"topologyElementIdentifier": "server-1",
"name": "Disk Usage"
},
{
"checkStateId": "checkStateId2",
"message": "Provisioning failed. [Learn more](https://www.any-link.com)",
"health": "critical",
"topologyElementIdentifier": "server-2",
"name": "Health monitor"
},
{
"checkStateId": "checkStateId3",
"delete": true
}
]
}
],
"topologies":[]
Every health Transactional Increments data payload has the following details:
- increment - An increment objects needs to be present on every message. This enables StackState to track the complete chain of messages and be able to detect when a retransmission of data, or an unexpected gap in the data is occurring. It carries the following fields as increment metadata:
- checkpoint - Object providing the checkpoint that belongs the the
check_statespresent in the message, it contains two fields:- offset - The offset asigned to the messages by the streaming pipeline (e.g. Kafka offset)
- batch_index - Optional. When using a single message to accumulate several
check_statesthe batch index represents the latest index that is present in the message, allowing to send big batches in separate api calls.
- previous_checkpoint - Optional. Represents the previously communicated checkpoint, can be empty on the very first transmission on the substream. It allows StackState to keep track if there could be any data missing from upstream.
- stream - Object providing identification regarding which snapshots and
check_statesbelong 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.
- delete - Flag that is interpreted as a delete request for the related
checkStateId. Even if the rest of the fields for the create are present, e.g.name, health, ...the delete will take precedence.
Health can be sent in one JSON message via HTTP POS. In the example below, a snapshot containing two check states is sent to StackState from a single external monitoring system.
curl
CLI: stac
CLI: sts (new)
curl -X POST \
'http://<STACKSTATE_BASE_URL>/stsAgent/intake?api_key=<STACKSTATE_RECEIVER_API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
"collection_timestamp": 1548857167,
"events": {},
"internalHostname": "localdocker.test",
"metrics": [],
"service_checks": [],
"topologies": [],
"health": [
{
"consistency_model": "TRANSACTIONAL_INCREMENTS",
"increment": {
"checkpoint": {
"offset": 5,
"batch_index": 102
},
"previous_checkpoint": {
"offset": 5,
"batch_index": 100
}
},
"stream": {
"urn": "urn:health:sourceId:streamId"
},
"check_states": [
{
"checkStateId": "checkStateId1",
"message": "Server Running out of disk space",
"health": "Deviating",
"topologyElementIdentifier": "server-1",
"name": "Disk Usage"
},
{
"checkStateId": "checkStateId2",
"message": "Provisioning failed. [Learn more](https://www.any-link.com)",
"health": "critical",
"topologyElementIdentifier": "server-2",
"name": "Health monitor"
},
{
"checkStateId": "checkStateId3",
"delete": true
}
]
}
]
}'
Sending of Transactional increments check_states is not available in the CLI, but all the debugging and introspection features can still be used.
⚠️ PLEASE NOTE - from StackState v5.0, the old
sts CLI is called stac.In a future release of StackState, the new
sts CLI will fully replace the stac CLI. It is advised to install the new sts CLI and upgrade any installed instance of the old sts CLI to stac. For details see:Sending of Transactional increments check_states is not available in the CLI. Use the
stac CLI for debugging and introspection features.Last modified 5mo ago