Integration SDK

StackState is an open platform that allows anyone to connect external systems to StackState using integrations. These integrations are packaged in StackPacks. Read on to find out how you can connect StackState to your own tools.

Background

StackState creates a real-time, always up-to-date map of your IT landscape. This landscape is expressed in a model, called the 4T data model. StackState’s functionality uses the data in the 4T data model, no matter the source of the data.

StackPacks and Integrations connect external systems to StackState and deliver data for one or more of the Ts in the model (Topology, Telemetry, Traces). The fourth T, Time, applies to all types of data.

Read the background article on the 4T data model to understand the types of data that integrations can deliver.

Data types

Before creating a new integration, you need to decide the type(s) of data the integration will deliver. This depends on the types of data available in the source system.

For example, a CMDB is a registry of (physical or virtual) IT components within your IT landscape. It can serve as a source of Topology information for StackState. Each IT asset in the CMDB can be represented as a component and connections between the assets as a relation.

In another example, a service such as AWS CloudWatch can serve as a Telemetry source. CloudWatch registers metrics about AWS resources and each of the metrics CloudWatch tracks can be registered in StackState.

Some systems can be a source for multiple types of data. Kubernetes, for instance, can be a source for both Topology (containers, pods, clusters and their relations) as well as Telemetry (metrics about pod performance, among others).

Planning a new integration

In StackState, telemetry is always mapped onto a component or relation. When creating a new integration, you should therefore always start with topology and add telemetry later.

If your integration is working, you can package it as a StackPack for distribution and installation.

Integrating topology

Topology data sent to StackState is processed in a number of steps which result in components and relations. The easiest way to get started is to use StackState’s default topology synchronization mechanism, which does a lot of the heavy lifting for you, provided you can deliver data in a pre-determined JSON format.

If you don’t have the option to do this, you can create a custom synchronization from scratch.

Integrating telemetry

Telemetry data can be pushed to StackState using a JSON data format. This telemetry guide explains how this works.

Packaging a StackPack

If your integration works, you can package it as a StackPack. Read this guide for more information.

Sample code

Writing a new integration is easiest if you have a sample to start with. Here are a few of our integrations that are part of our open-source StackState agent: