Send telemetry data over HTTP

Search…
StackState version 5.0
StackState Self-hosted v5.0.x
Overview
StackState can either pull telemetry from a data source or can receive pushed telemetry. Pushed telemetry is stored by StackState, while pulled telemetry is not. Pushed telemetry is stored for the duration of the configured retention period. This page describes how telemetry can be pushed.
There are several ways to send telemetry to StackState. A large number of integrations are provided out of the box that may help you get started. If there is no out of the box integration you can send telemetry to StackState using either HTTP or the StackState stac CLI.
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://<STACKSTATE_BASE_URL>/receiver/stsAgent/intake?api_key=<STACKSTATE_RECEIVER_API_KEY>
Copied!
The <STACKSTATE_BASE_URL> and <STACKSTATE_RECEIVER_API_KEY> are set during StackState installation, for details see Kubernetes install - configuration parameters.
1
https://<STACKSTATE_BASE_URL>:<STACKSTATE_RECEIVER_PORT>/stsAgent/intake?api_key=<STACKSTATE_RECEIVER_API_KEY>
Copied!
The <STACKSTATE_BASE_URL> and <STACKSTATE_RECEIVER_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. One message can contain multiple metrics and multiple events.
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!
Depending on your StackState configuration, received metrics or events that are too old will be ignored.
Metrics
Metrics can be sent to the StackState Receiver API using the "metrics" property of the common JSON object.
JSON property: "metrics"
Example metric JSON
1
[
2
  "test.metric", // the metric name
3
  1548857152,
4
  10.0, // double - value of the metric
5
  {
6
    "hostname": "localdocker.test",
7
    "tags": [ 
8
      "tag_key1:tag_value1",
9
      "tag_key2:tag_value2"
10
    ],
11
    "type": "gauge"
12
  }
13
]
Copied!
Every metric has the following details:
name - The metric name. Must not start with any of the following prefixes: host, labels, name, tags , timeReceived, timestamp, tags or values.
timestamp - The epoch timestamp of the metric.
value - The value of the metric.
hostname - The host this metric is from.
type - The type of metric. Can be gauge, count, rate, counter or raw.
tags - Optional. A list of key/value tags to associate with the metric.
The timestamp and value are used to plot the metric as a time series. The name and tags can be used to define a metric stream in StackState.
Send metrics to StackState
Multiple metrics can be sent in one JSON message via HTTP POST. For example:
curl
1
curl -X POST \
2
 'http://<STACKSTATE_BASES_URL>/stsAgent/intake?api_key=<STACKSTATE_RECEIVER_API_KEY>' \
3
 -H 'Content-Type: application/json' \
4
 -d '{
5
  "collection_timestamp": 1548857167,
6
  "events": {},
7
  "internalHostname": "localdocker.test",
8
  "metrics": [
9
    [
10
      "test.metric",
11
      1548857152,
12
      10.0,
13
      {
14
        "hostname": "localdocker.test",
15
        "tags": [
16
          "tag_key1:tag_value1",
17
          "tag_key2:tag_value2"
18
        ],
19
        "type": "gauge"
20
      }
21
    ],
22
    [
23
      "test.metric",
24
      1548857167,
25
      10.0,
26
      {
27
        "hostname": "localdocker.test",
28
        "tags": [
29
          "tag_key1:tag_value1",
30
          "tag_key2:tag_value2"
31
        ],
32
        "type": "gauge"
33
      }
34
    ]
35
  ],
36
  "service_checks": [],
37
  "topologies": []
38
}'
Copied!
You can also send metrics to StackState using the stac CLI metric send command.
Events
Events can be sent to the StackState Receiver API using the "events" property of the common JSON object.
All events in StackState relate to a topology element or elements. Any properties of an event can be used to define a log stream in StackState.
JSON property: "events"
Example event JSON
1
"event.test": [ // The event name
2
  {
3
    "context": {
4
      "category": "Changes",
5
      "data": { 
6
        "data_key1":"data_value1",
7
        "data_key2":"data_value2"
8
      },
9
      "element_identifiers": [
10
        "element_identifier1",
11
        "element_identifier2"
12
      ],
13
      "source": "source_system",
14
      "source_links": [
15
        {
16
          "title": "link_title",
17
          "url": "link_url"
18
        }
19
      ]
20
    },
21
    "event_type": "event_typeEvent",
22
    "msg_title": "event_title",
23
    "msg_text": "event_text",
24
    "source_type_name": "source_event_type",
25
    "tags": [
26
      "tag_key1:tag_value1",
27
      "tag_key2:tag_value2",
28
    ],
29
    "timestamp": 1607432944
30
  }
31
]
Copied!
Events have the following details:
An event name. this must not start with any of the following prefixes: eventType, host, labels, message, name, tags, timeReceived, timestamp or title.
context - Optional. Includes details of the source system for an event. Events that contain a context will be visible in the StackState Events Perspective for views that contain a component with a matching source identifier. Events without a context will be available in StackState as a log stream:
category - The event category. Can be Activities, Alerts, Anomalies, Changes or Others.
element_identifiers - The identifiers for the topology element(s) the event relates to. These are used to bind the event to a topology element or elements.
source - The name of the system from which the event originates, for example AWS, Kubernetes or JIRA.
data - Optional. A list of key/value details about the event, for example a configuration version.
source_identifier - Optional. The original identifier of the event in the source system.
source_links - Optional. A list of links related to the event, for example a dashboard or the event in the source system.
event_type - Describes the event being sent. This should generally end with the suffix Event, for example ConfigurationChangedEvent, VersionChangedEvent.
msg_text - Required. The text body of the event.
msg_title - Required. The title of the event.
source_type_name - Optional. The source event type name.
tags - Optional. A list of key/value tags to associate with the event.
timestamp - The epoch timestamp for the event.
Send events to StackState
Multiple events can be sent in one JSON message via HTTP POST. You can also send a single event to StackState using the stac CLI event send command. For example:
curl
CLI: stac
CLI: sts (new)
1
curl -X POST \
2
 'http://<STACKSTATE_BASE_URL>/stsAgent/intake?api_key=<STACKSTATE_RECEIVER_API_KEY>' \
3
 -H 'Content-Type: application/json' \
4
 -d '{
5
  "collection_timestamp": 1548857342,
6
  "events": {
7
    "event.test01": [ // The event name
8
      {
9
        "context": {
10
          "category": "Changes",
11
          "data": { 
12
            "data_key1":"data_value1",
13
            "data_key2":"data_value2"
14
          },
15
          "element_identifiers": [
16
            "element_identifier1",
17
            "element_identifier2"
18
          ],
19
          "source": "source_system",
20
          "source_links": [
21
            {
22
              "title": "link_title",
23
              "url": "link_url"
24
            }
25
          ]
26
        },
27
        "event_type": "HealthStateChangedEvent",
28
        "msg_title": "event_title",
29
        "msg_text": "event_text",
30
        "source_type_name": "source_event_type",
31
        "tags": [
32
          "tag_key1:tag_value1",
33
          "tag_key2:tag_value2",
34
        ],
35
        "timestamp": 1607432944
36
      }
37
    ],
38
    "event.test02": [ // The event name
39
      {
40
        "context": {
41
          "category": "Changes",
42
          "data": { 
43
            "data_key1":"data_value1",
44
            "data_key2":"data_value2"
45
          },
46
          "element_identifiers": [
47
            "element_identifier1",
48
            "element_identifier2"
49
          ],
50
          "source": "source_system",
51
          "source_links": [
52
            {
53
              "title": "link_title",
54
              "url": "link_url"
55
            }
56
          ]
57
        },
58
        "event_type": "HealthStateChangedEvent",
59
        "msg_title": "event_title",
60
        "msg_text": "event_text",
61
        "source_type_name": "source_event_type",
62
        "tags": [
63
          "tag_key1:tag_value1",
64
          "tag_key2:tag_value2",
65
        ],
66
        "timestamp": 1607432944
67
      }
68
    ]
69
  "internalHostname": "localdocker.test",
70
  "metrics": [],
71
  "service_checks": [],
72
  "topologies": []
73
}'
Copied!
1
stac event send "HealthStateChangedEvent" \
2
    --title "event_title" \
3
    -i "element_identifier1" "element_identifier2" \
4
    -s "source_system" \
5
    -c "Changes" \
6
    -d '{"data_key1":"data_value1", "data_key2":"data_value2"}' \
7
    --links "link_title1: link_url1" "link_title2: link_url2"
Copied!
Command not available in the new sts CLI. Use the stac CLI.
See also
​StackState identifiers​
​Events Perspective​
​Events tutorial​
Prometheus mirror
Set the default telemetry interval
Last modified 9d ago
Copy link
Contents
Overview
StackState Receiver API
Common JSON object
Metrics
JSON property: "metrics"
Send metrics to StackState
Events
JSON property: "events"
Send events to StackState