# Send events over HTTP ## Overview StackState can either pull events from a data source or can receive pushed events. Pushed events are stored by StackState, while pulled events aren't. Pushed events are stored for the duration of the configured retention period. This page describes how events can be pushed. There are several ways to send events to StackState. A large number of [integrations](https://archivedocs.stackstate.com/5.1/stackpacks/integrations) are provided out of the box that may help you get started. If there is no out of the box integration available, you can send events to StackState using either HTTP or the [StackState `stac` CLI](https://archivedocs.stackstate.com/5.1/setup/cli/cli-stac). ## StackState Receiver API The StackState Receiver API accepts topology, metrics, events and health data in a common JSON object. The default location for the receiver API is the ``, constructed using the `` and <`STACKSTATE_RECEIVER_API_KEY>`. {% tabs %} {% tab title="Kubernetes" %} The `` for StackState deployed on Kubernetes or OpenShift is: ``` https:///receiver/stsAgent/intake?api_key= ``` The `` and `` are set during StackState installation, for details see [Kubernetes install - configuration parameters](https://archivedocs.stackstate.com/5.1/setup/install-stackstate/kubernetes_openshift/kubernetes_install#generate-values-yaml). {% endtab %} {% tab title="Linux" %} The `` for StackState deployed on Linux is: ``` https://:/stsAgent/intake?api_key= ``` The `` and `` are set during StackState installation, for details see [Linux install - configuration parameters](https://archivedocs.stackstate.com/5.1/setup/install-stackstate/linux/install_stackstate#configuration-options-required-during-install). {% endtab %} {% endtabs %} ## Common JSON object Topology, metrics, event and health data are sent to the StackState receiver API via HTTP POST. There is a common JSON object used for all messages. One message can contain multiple metrics and multiple events. ```javascript { "collection_timestamp": 1548855554, // the epoch timestamp for the collection in seconds "events": {}, // see the section on "events", below "internalHostname": "local.test", // the host sending this data "metrics": [], // see the section on "metrics", below "service_checks": [], "topologies": [], // used for sending topology data "health": // used for sending health data } ``` {% hint style="info" %} Depending on your StackState configuration, received events that are too old will be ignored. {% endhint %} ## JSON property: "events" Events can be sent to the StackState Receiver API using the `"events"` property of the [common JSON object](https://archivedocs.stackstate.com/5.1/configure/send_metrics#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. {% tabs %} {% tab title="Example event JSON" %} ```javascript "event.test": [ { "context": { "category": "Changes", "data": { "data_key1":"data_value1", "data_key2":"data_value2" }, "element_identifiers": [ "element_identifier1", "element_identifier2" ], "source": "source_system", "source_links": [ { "title": "link_title", "url": "link_url" } ] }, "event_type": "event_typeEvent", "msg_title": "event_title", "msg_text": "event_text", "source_type_name": "source_event_type", "tags": [ "tag_key1:tag_value1", "tag_key2:tag_value2" ], "timestamp": 1607432944 } ] ``` {% endtab %} {% endtabs %} 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`. In the example above, the event name is `event.test`. * **context** - Optional. Includes details of the source system for an event. Events that contain a context will be visible in the StackState [Events Perspective](https://archivedocs.stackstate.com/5.1/use/stackstate-ui/perspectives/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)](https://archivedocs.stackstate.com/5.1/topology/identifiers#topology-identifiers) 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: {% tabs %} {% tab title="curl" %} ```bash curl -X POST \ 'https:// \ -H 'Content-Type: application/json' \ -d '{ "collection_timestamp": 1548857342, "internalHostname": "local.test", "events": { "event.test01": [ { "context": { "category": "Changes", "data": { "data_key1":"data_value1", "data_key2":"data_value2" }, "element_identifiers": [ "element_identifier1", "element_identifier2" ], "source": "source_system", "source_links": [ { "title": "link_title", "url": "link_url" } ] }, "event_type": "event_type", "msg_title": "event_title", "msg_text": "event_text", "source_type_name": "source_event_type", "tags": [ "tag_key1:tag_value1", "tag_key2:tag_value2" ], "timestamp": 1607432944 } ], "event.test02": [ { "context": { "category": "Changes", "data": { "data_key1":"data_value1", "data_key2":"data_value2" }, "element_identifiers": [ "element_identifier1", "element_identifier2" ], "source": "source_system", "source_links": [ { "title": "link_title", "url": "link_url" } ] }, "event_type": "event_type", "msg_title": "event_title", "msg_text": "event_text", "source_type_name": "source_event_type", "tags": [ "tag_key1:tag_value1", "tag_key2:tag_value2" ], "timestamp": 1607432944 } ] } }' ``` {% endtab %} {% tab title="CLI: stac (deprecated)" %} ``` stac event send "event_type" \ --title "event_title" \ -i "element_identifier1" "element_identifier2" \ -s "source_system" \ -c "Changes" \ -d '{"data_key1":"data_value1", "data_key2":"data_value2"}' \ --links "link_title1: link_url1" "link_title2: link_url2" ``` ⚠️ **From StackState v5.0, the old `sts` CLI is called `stac`. The old CLI is now deprecated.** The new `sts` CLI replaces the `stac` CLI. It's advised to install the new `sts` CLI and upgrade any installed instance of the old `sts` CLI to `stac`. For details see: * [Which version of the `sts` CLI am I running?](https://archivedocs.stackstate.com/5.1/setup/cli/cli-comparison#which-version-of-the-cli-am-i-running) * [Install the new `sts` CLI and upgrade the old `sts` CLI to `stac`](https://archivedocs.stackstate.com/5.1/setup/cli/cli-sts#install-the-new-sts-cli) * [Comparison between the CLIs](https://archivedocs.stackstate.com/5.1/setup/cli/cli-comparison) {% endtab %} {% tab title="CLI: sts" %} Command not available in the new `sts` CLI. Use the `stac` CLI. {% endtab %} {% endtabs %} ## See also * [StackState identifiers](https://archivedocs.stackstate.com/5.1/configure/topology/identifiers) * [Events Perspective](https://archivedocs.stackstate.com/5.1/use/stackstate-ui/perspectives/events_perspective) * [Events tutorial](https://archivedocs.stackstate.com/5.1/develop/tutorials/events_tutorial)