StackState CLI

Search…
StackState version 4.2 (EOL)
StackState CLI
Managing StackState using the CLI.
This page describes StackState version 4.2.
The StackState 4.2 version range is End of Life (EOL) and no longer supported. We encourage customers still running the 4.2 version range to upgrade to a more recent release.
Go to the documentation for the latest StackState release.
The StackState CLI can be used to configure StackState, work with data, and help with debugging problems. The CLI provides easy access to the functionality provided by the StackState API. The URLs and authentication credentials are configurable. Multiple configurations can be stored for access to different instances.
Install the StackState CLI
A standalone executable is available to run the StackState CLI on Linux and Windows. You can also run the CLI inside a Docker container on Linux, Windows or MacOS.
Linux install
A standalone executable file is available to run the StackState CLI on Linux.
Requirements:
Access to the StackState APIs.
Installation:
1.Download the Linux executable sts-cli-VERSION-linux64 from https://download.stackstate.com.
2.Rename the downloaded file to be sts and make it executable:
1
mv sts-cli-VERSION-linux64 sts
2
chmod +x sts
Copied!
3.(optional) Place the file under your PATH to use StackState CLI commands from anywhere on the command line.
4.Follow the steps below to launch the configuration wizard or manually configure the StackState CLI.
Windows install
A standalone executable file is available to run the StackState CLI on Windows.
Requirements:
Access to the StackState APIs.
Installation:
1.Download the executable sts-cli-VERSION-windows.exe from https://download.stackstate.com.
2.Rename the downloaded file to be sts.exe.
3.(optional) Place the file under your PATH to use StackState CLI commands from anywhere on the command line.
4.Follow the steps below to launch the configuration wizard or manually configure the StackState CLI.
Docker install (Mac, Linux, Windows)
The StackState CLI can be run inside a Docker container on Linux, Windows or MacOS. The ZIP archive provided contains scripts that help you run the CLI without needing to worry about Docker invocations.
Requirements:
Access to the StackState APIs.
​Docker installed.
Internet connection for first time run.
Installation:
1.Download the ZIP file sts-cli-VERSION.zip from https://download.stackstate.com.
The ZIP archive contains the following files:
1
.
2
+-- bin
3
|   +-- sts     # Script to run the CLI in Docker for bash
4
|   +-- sts.ps1 # Script to run the CLI in Docker for Powershell
5
+-- conf.d
6
|   +-- conf.yaml.example # Example CLI configuration
7
|   +-- VERSION           # The CLI version to retrieve from Docker hub
8
+-- templates
9
|   +-- topology   # Topology templates in a format specific to the CLI
10
+-- release_notes.md  # Changelog of the CLI
11
+-- usage.md          # How to configure and use this package
Copied!
2.(optional) Put put the bin folder to your PATH to use StackState CLI commands from anywhere on the command line.
3.Follow the steps below to manually configure the StackState CLI.
Configure the StackState CLI
To use the StackState CLI, you need to configure it with the API connection details for your StackState instance.
Linux or Windows install: A wizard will guide you through configuration or you can create the configuration file manually.
Docker install: Create the configuration file manually.
Wizard configuration (Linux and Windows install)
The configuration generated by the wizard will only work when StackState has been configured to use either LDAP authentication or the file-based authentication. When using OIDC or KeyCloak authentication, follow the directions in the manual configuration section.
The binary files downloaded in the Linux and Windows install methods described above include a configuration wizard to generate the StackState CLI configuration file. The first time you run any sts command, the StackState CLI will look for a configuration file. If no valid configuration file is found, the wizard will guide you through creating one and store it under the user's home directory.
For example:
1
$ sts graph list-types
2
No config was found. Would you like to configure CLI using wizard? (y/N) y
3
​
4
Base API URL (default - http://localhost:7070/) https://mystackstate.example.org
5
    username (empty if no auth) admin
6
    password secretpassword
7
Receiver API URL (default - https://mystackstate.example.org:7077) https://mystackstate.example.org/receiver
8
    username (empty if no auth) (default - admin)
9
    password (default - secretpassword)
10
Admin API URL (default - https://mystackstate.example.org:7071) https://mystackstate.example.org/admin
11
    username (empty if no auth) (default - admin)
12
    password (default - secretpassword)
13
API key (default - API_KEY) a912bc82d89dfba72def
14
Hostname used for ingested via CLI (default - hostname)
Copied!
Manual configuration
Follow the steps below to create a configuration file manually (required for Docker install).
1.Download the ZIP file sts-cli-VERSION.zip from https://download.stackstate.com. If you ran the Docker install, skip this step and use the ZIP archive you already downloaded.
2.Copy the file conf.d/conf.example.yaml from the ZIP archive and put it in one of the following directories:
Docker:
conf.d/ - relative to the directory where the CLI is run.
Linux or Windows:
conf.d/ - relative to the directory where the CLI is run.
~/.stackstate/cli/ - relative to the user's home directory.
%APPDATA%/StackState/cli/ - relative to the user's home directory.
3.Rename the file to be conf.yaml.
4.Edit the file and add:
URLs to the StackState APIs.
Any required authentication details for the APIs.
Client details.
The base_api API has support for API Tokens. You can copy your private API Token from the "User Profile" page on the UI of StackState.
For example:
1
instances:
2
 default:
3
   base_api:
4
     url: "https://localhost:7070"
5
     ## StackState authentication. This type of authentication is exclusive to the `base_api`.
6
     apitoken_auth:
7
      token: "your API Token"
8
   receiver_api:
9
     url: "https://???:7077"
10
     ## HTTP basic authentication.
11
     #basic_auth:
12
       #username: "validUsername"
13
       #password: "safePassword"
14
   admin_api:
15
     url: "https://???:7071"
16
     ## HTTP basic authentication.
17
     #basic_auth:
18
       #username: "adminUsername"
19
       #password: "safePassword"
20
​
21
   ## The CLI uses a client configuration to identify who is sending to the StackState instance. The client
22
   ## is used to send topology and/or telemetry to the receiver API.
23
   ##
24
   ## Unless the `--client` argument is passed the CLI will pick the `default` instance as configured below.
25
   ## Other clients follow the exact same configuration pattern as the default client. You may simply copy-paste its config and modify whatever is needed.
26
   clients:
27
     default:
28
       api_key: "???"
29
       ## The name of the host that is passed to StackState when sending. Leave these values unchanged
30
       ## if you have no idea what to fill here.
31
       hostname: "hostname"
32
       internal_hostname: "internal_hostname"
Copied!
Multiple configurations
The conf.yaml configuration file can hold multiple configurations. Other StackState instances can be added on the same level as the default configuration. For example:
1
instances:
2
 default:
3
   base_api:
4
     ...
5
   clients:
6
     ...
7
 Preproduction:
8
   base_api:
9
     ...
10
   clients:
11
     ...
Copied!
To use the StackState CLI with a non-default instance:
1
sts --instance <instance_name> ...
Copied!
Use the StackState CLI
Import and export StackState configuration
The StackState configuration is stored in StackState's graph database in so-called configuration nodes. These nodes can be inspected, imported and exported using the CLI.
1
# See all types of configuration nodes:
2
sts graph list-types
Copied!
You can use the sts graph export and sts graph import commands to export and import different types of configuration nodes from and to StackState. Nodes are stored in StackState Templated Json format.
For example:
1
# Write all check functions to disk
2
sts graph list --ids CheckFunction | xargs sts graph export --ids > mycheckfunctions.stj
3
​
4
# Import check functions from file
5
sts graph import < mycheckfunctions.stj
Copied!
Inspect data
All data flowing through StackState (e.g. topology, telemetry, traces, etc.) flows through so-called topics. For debugging purposes, these topics can be inspected using the CLI. This can come in handy, for example, to make sure that StackState is receiving data correctly when you write your own integrations.
For example:
1
# See all topics
2
sts topic list
3
​
4
# Inspect a topic
5
sts topic show <topic>
Copied!
Send data
You may not always want to try a new configuration on real data. First, you might want to see if it works correctly with predictable data. The CLI makes it easy to send test topology or telemetry data to StackState.
​Send metrics data​
​Send events data​
​Send topology data​
​Send anomaly data​
Metrics
The CLI provides some predefined settings to send metrics to StackState. Run the below command without any optional arguments to send one data point of the given value:
1
sts metric send <MetricName> <OptionalNumberValue>
Copied!
You can also use optional arguments to create historical data for a test metric.
Argument
Details
-p
Time period. This can be in weeks w, days d, hours h, minutes m and/or seconds s. For example: -p 4w2d6h30m15s
-b
The bandwidth between which values will be generated. For example: -b 100-250
By default, a metrics pattern is random or, when a value is provided, a flatline. This can be changed using the pattern arguments --linear and --baseline.
Argument
Details
--linear
Creates a line between the values given for -b plotted over the time given for -p
--baseline
Creates a daily usage curve. On Saturday and Sunday, the metric is much lower than on weekdays. The min and max of the curve are set by -b and -p
--csv
Reads a CSV file from the stdin and sends it to StackState. The content of the CSV file should be in the format timestamp,value
To see all available options, use:
1
sts metric send -h
Copied!
Events
The CLI can send events using sts evens send <eventName> It will send one event with the given name.
For help on sending events data, use:
1
sts event send -h
Copied!
Topology
Please refer to usage.md in the CLI zip archive for detailed instructions.
For help on sending topology data, use:
1
sts topology send -h
Copied!
Anomaly
The CLI provides an anomaly command used to send anomaly data for a metric stream of a component.
1
sts anomaly send --component-name <Component> --stream-name <Metric Stream> --start-time=-30m
Copied!
You can also use the optional arguments below to create a specific anomaly.
Argument
Details
--duration
Anomaly duration (seconds)
--severity
Anomaly severity (HIGH, MEDIUM, LOW)
--severity-score
Anomaly severity score
--description
Anomaly description field contents
For help on sending anomaly data, use:
1
sts anomaly send -h
Copied!
Manage StackPacks
The StackState CLI can be used to manage the StackPacks in your StackState instance.
​Install a StackPack​
​Upgrade a StackPack​
​Uninstall a StackPack​
Install a StackPack
To install a StackPack, you must first upload it to the StackState server.
1
# Upload a StackPack
2
sts stackpack upload /path/to/MyStackPack-1.0.0.sts
3
​
4
# Install an uploaded StackPack
5
sts stackpack install MyStackPack
6
​
7
# Provide parameters for StackPack install:
8
sts stackpack install -p param1 value1 -p param2 value2 MyStackPack
Copied!
For example, the open-source SAP StackPack requires the parameter sap_host during installation. This command kicks off that installation:
1
sts stackpack install -p sap_host sap1.acme.com sap
Copied!
Upgrade a StackPack
If you want to upgrade a StackPack, first upload the new StackPack version to the StackState server, then trigger the upgrade with the following command:
1
# Upload new StackPack version
2
sts stackpack upload /path/to/MyStackPack-1.0.1.sts
3
​
4
# Upgrade to the uploaded StackPack
5
sts stackpack upgrade MyStackPack
Copied!
Note that StackState will upgrade to the latest StackPack version available on the StackState server.
Uninstall a StackPack
Uninstall a StackPack as follows:
1
sts stackpack uninstall MyStackPack
Copied!
Scripting
It is possible to execute scripts using the StackState CLI. Use sts script to execute a script via standard input. For example:
1
echo "Topology.query(\"label IN ('stackpack:aws')\")" | sts script execute
Copied!
Note that the script provided as input must use proper quoting.
License
The StackState CLI can check your license validity and update a license key when needed, for example in case of expiration.
1
# check license key validity
2
sts subscription show
3
​
4
# Update license key
5
sts subscription update new-license-key
Copied!
Note that it is not necessary to do this via the CLI. StackState will also offer this option in the UI when a license is about to expire or has expired.