Send topology data over HTTP
StackState Self-hosted v4.6.x
Overview
StackState can synchronize topology information from different sources, including your own sources.
The easiest way to connect StackState to one of your data sources is to use a StackPack. StackPacks are standard integrations that configure StackState to consume data from a particular data source or platform.
You can also create a custom topology synchronization and send topology data to StackState in JSON format. Received JSON files pass through a number of processing steps. At the end of this synchronization pipeline, the incoming data is stored as components and relations in the StackState topology.
StackState Receiver API
The StackState Receiver API accepts topology, telemetry and health data 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
Topology, telemetry and health data are sent to the receiver API via HTTP POST. There is a common JSON object used for all messages.
1
{
2
"collection_timestamp": 1548855554, // the epoch timestamp for the collection
3
"events": {}, // used for sending events data
4
"internalHostname": "localdocker.test", // the host that is sending this data
5
"metrics": [], // used for sending metrics data
6
"service_checks": [],
7
"topologies": [], // used for sending topology data
8
"health" // used for sending health data
9
}
Copied!
JSON property: "topologies"
StackState accepts topology information in the following JSON format:
1
{
2
"apiKey":"your api key",
3
"collection_timestamp":1585818978,
4
"internalHostname":"lnx-343242.srv.stackstate.com",
5
"events":{},
6
"metrics":[],
7
"service_checks":[],
8
"health":[],
9
"topologies":[
10
{
11
"start_snapshot": false,
12
"stop_snapshot": false,
13
"instance":{
14
"type":"mesos",
15
"url":"http://localhost:5050"
16
},
17
"delete_ids": ["nginx4.3ff3a4d2-fa7e-4b11-b74c-acad9d4f5ea0"],
18
"components":[
19
{
20
"externalId":"nginx3.e5dda204-d1b2-11e6-a015-0242ac110005",
21
"type":{
22
"name":"docker"
23
},
24
"data":{
25
"ip_addresses":[
26
"172.17.0.8"
27
],
28
"labels":["label1", "category:"label2"],
29
"framework_id":"fc998b77-e2d1-4be5-b15c-1af7cddabfed-0000",
30
"task_name":"nginx3",
31
"slave_id":"fc998b77-e2d1-4be5-b15c-1af7cddabfed-S0"
32
},
33
"sourceProperties":{
34
"docker":{
35
"image":"nginx",
36
"network":"BRIDGE",
37
"port_mappings":[
38
{
39
"container_port":31945,
40
"host_port":31945,
41
"protocol":"tcp"
42
}
43
],
44
"privileged":false
45
}
46
},
47
}
48
],
49
"relations":[
50
{
51
"externalId":"nginx3.e5dda204-d1b2-11e6-a015-0242ac110005->nginx5.0df4bc1e-c695-4793-8aae-a30eba54c9d6",
52
"type":{
53
"name":"uses_service"
54
},
55
"sourceId":"nginx3.e5dda204-d1b2-11e6-a015-0242ac110005",
56
"targetId":"nginx5.0df4bc1e-c695-4793-8aae-a30eba54c9d6",
57
"data":{
58
59
}
60
}
61
]
62
}
63
]
64
}
Copied!
The JSON contains the following fields:
- apiKey: The key that StackState provided for your installation.
- collection_timestamp: Collection timestamp in Epoch seconds. Depending on your StackState configuration, topology that is to old may be ignored.
- internalHostname: The hostname of the collector (which sends your custom topology data).
- topologies: A list of one or more instance types. Instance types are described by the following fields:
- start_snapshot: Boolean (true/false). When set to "true" this message is handled as the beginning of a snapshot. This enables StackState to diff snapshots with the previous one to delete components / relations which are not in the snapshot anymore.
- stop_snapshot: Boolean (true/false). When set to "true" this message is handled as the end of a snapshot.
- delete_ids: List of external ids. List of components or relations that should be deleted. All components and relations that are not repeated in a snapshot will be deleted automatically, thus this field is only necessary when not sending a snapshot.
- instance: Describes the type and unique ID (URL format) of the topology data.
- type: A type name for the topology data.
- URL: Unique identifier for the source of this topology. This is used to generate a unique Kafka topic name for the topology data.
- components: A list of components. Each component has the following fields:
- externalId: A unique ID for this component. This has to be unique for this instance.
- type: A named parameter for this type.
- data: A JSON blob of arbitrary data.
- sourceProperties: Optional. A JSON blob of arbitrary data. When populated, the contents of this field will be displayed in the StackState UI component properties in place of the
datafield. Thedatafield will still be accessible in templates and the various functions that make use of this data
- relations: A list of relations. Each relation has the following fields:
- externalId: A unique ID for this relation. This has to be unique for this instance.
- type: A named parameter for this type.
- data: A JSON blob of arbitrary data.
- sourceId: The source component externalId.
- targetId: The target component externalId.
Get started with custom topology
The push-integration tutorial is a good way to get started sending your own topology into StackState.
See also
Last modified 3d ago