Synchronizations and templated files
StackState Self-hosted v5.1.x
To obtain the .stj
Templated file for your StackPack you need to perform a few steps in StackState Settings page and then edit the template file by hand.
Every .stj template is filled with information about the hosts and environments that StackState collects data from. Example of this information looks like this:
How to get a templated file for your StackPack
Preparing a templated file is a process that requires some configuration of StackState. To get the above file in a structure that can be used to create a StackPack, follow the below route:
1. Prepare a check in StackState Agent
2. Install Custom Synchronization StackPack
To install this StackPack go to StackState's StackPacks section and locate the "Custom Synchronization" in Other StackPacks. During the installation process, you need to enter the following information:
Instance type (source identifier) - this is the identifier for the resource that you want to integrate with StackState, for example, AWS, Azure and Zabbix.
Instance URL - The URL of the instance the data is being reported for.
When the above information is provided click the "Install" button and if Agent V3 checks are working you should start to see the topology coming in for your integration and the "Custom Synchronization" should become enabled.
3. Configure Layers, Domains, and Environments
Once you have installed Custom Synchronization StackPack, you need to start preparing the configuration that's needed for your integration.
There are some default Layers, Domains, and Environments created by StackState. Layers are used for vertical separation between components; Domains are used for horizontal separation between components; Environments are grouping components. You can add custom Layers, Domains, and Environments in the Settings pages to match your StackPack needs.
4. Configure Component and Relation types
Component types and Relation types can also be created automatically by StackState using the getOrCreate
functionality described in the Component + Relation Templates
section. Auto-generated components types will be created without an icon.
5. Prepare ID Extractor Functions
When creating a StackPack, it's important to have a component
and relation
identity extractor function. There are a few default ID Extractor Functions present in StackState. The Auto sync component id extractor
and Auto sync relation id extractor
are good starting points for your StackPack. You can go ahead and rename these, add a description if needed, and confirm the popup dialog to unlock these ID Extractor Functions from the Custom Synchronization
StackPack.
6. Prepare Component and Relation Mapping Functions
Component Mapping Functions are used by StackState to do some translation of incoming component data. They're applied in the Synchronization for a given source/component type.
7. Configure Component and Relation Templates
Once you have installed the Custom Synchronization
StackPack, it creates a Component Template called autosync-component-template
. Similarly, Custom Synchronization
StackPack, creates a Relation Template called autosync-relation-template
.
Once you have completed all the changes, you can click UPDATE and confirm the popup dialog to unlock this Template from the Custom Synchronization
StackPack.
8. Configure Sts Sources - Topology Sources
Once you have completed all the changes, you can click UPDATE and confirm the popup dialog to unlock this StackState DataSource from the Custom Synchronization
StackPack.
9. Configure Synchronizations
Step 1
We recommend that you change the Synchronization Name
and add a Description
if needed. There is no action required on Plugin
, it uses the Sts
plugin to synchronize data from StackState Agent V3.
Step 2
There is no action needed here. However, you can observe the data source, component, and relation identity extractor, as well as whether this synchronization processes historical data. The recommended setting here is to keep this setting off.
Step 3
This is where the Component Mappings are defined. The Custom Synchronization
StackPack defines a default component mapping
which can be seen at the bottom of the wizard for all "Other Sources".
Here you can define all your own components mappings for different resources.
Step 4
This is where the Relation Mappings are defined. The Custom Synchronization
StackPack defines a default relation mapping
which can be seen at the bottom of the wizard for all Other Sources
.
Here you can define all your own relation mappings for different sources.
Step 5
Verify all the changes and click "Save". On the popup dialog that appears right after saving click "Confirm" to unlock this synchronization from the Custom Synchronizations
StackPacks.
10. Export the StackState Configuration
When your integration is working and has a shape that you expect, you can convert StackState's configuration into a StackPack template file. To do this go to the Settings page and at the bottom of the left menu, you can find an Import/Export section. Click on the STS-EXPORT-ALL-{Date}.conf
button on the main screen. This exports all of StackState's configuration into a config file format.
The configuration file has the following format:
11. Convert your StackState configuration file to the .stj
template
.stj
templateEach of the node elements represents a configuration item in StackState. This config file has all the configuration of your StackState instance, which means you have to take out unnecessary configuration node objects. Take the steps below to convert your configuration file into an .stj
template file:
Remove all configuration
node
objects that are owned by another StackPack. They all have a field calledownedBy
.StackState uses an urn-based identifiers, you can go ahead and define an urn for each of your configuration objects.
Items that are extended from the
Custom Synchronization
StackPack, will have their urnidentifier
field with the following structure:urn:stackpack:autosync:{type_name}:{object_name}
.Typical
identifier
pattern that you can find across our StackPacks configuration is:urn:stackpack:{stackpack_name}:{type_name}:{object_name}
For StackPacks that can have multiple instances the identifier has a slightly different pattern:
urn:stackpack:{stackpack_name}:instance:{{instanceId}}:{type_name}:{object_name}
where{{instanceId}}
is uniquely genrated for every instance of the StackPack.
The only way to add/modify the identifiers is the manual edit of the configuration file. This option will be available also through UI in the upcoming releases.
One common example is to create the topic name required by the data source for a given instance. To ensure data received from the StackState Agent Check ends up in your StackPack's data source, make sure that you create the same topic in the provisioning script. Following code snippet shows how to create a function called topicName
that generates a topic name for this instance based on the data provided by the user in the StackPack installation step.
It's possible now to reference any of the above templateArguments
in your .stj
template file. In case of the topicName
you can replace the topic
value in the config
section of your StackState DataSource with this parameter:
Last updated