Transactional Increments JSON
StackState Self-hosted v5.1.x
Last updated
StackState v5.1
StackState Self-hosted v5.1.x
Last updated
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 .
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 check_states present in the message, it has two fields:
offset - The offset asigned to the messages by the streaming pipeline. For example, Kafka offset.
batch_index - Optional. When using a single message to accumulate several check_states the batch index represents the latest index that's 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_states belong together. It has the following fields:
sub_stream_id - Optional. Identifier for a subset 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's interpreted as a delete request for the related checkStateId. Even if the rest of the fields for the create are present, for example, name, health, ... the delete will take precedence.
Health can be sent in one JSON message via HTTP POST. In the example below, a snapshot containing two check states is sent to StackState from a single external monitoring system.
urn - Data source and stream ID encoded as a StackState 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.