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.
The CLI can be downloaded from https://download.stackstate.com using your license key.
The downloaded zip contains the following:
. +-- bin | +-- sts +-- conf.d | +-- conf.yaml.example | +-- VERSION +-- templates +-- topology
stsis the cli. Put sts on your path to use it anywhere on the command line.
conf.yaml.exampledocuments how to configure the url and credentials.
VERSIONthe version of the cli.
templatesthese are topology templates in a format specific to the cli.
The cli searches for configuration in
conf.d/conf.yaml. You need to create this file. In this file the URLs to the sts APIs, their authentication (if any), and a client must be defined. You can copy the
conf.d/conf.example.yaml file and rename it to
conf.yaml to get you started. Or copy the example below.
instances: default: base_api: url: "https://???" ## StackState authentication. This type of authentication is exclusive to the `base_api`. # auth: # username: "???" # password: "???" ## HTTP basic authentication. # basic_auth: # username: "???" # password: "???" receiver_api: url: "https://???:7077" ## HTTP basic authentication. #basic_auth: #username: "???" #password: "???" admin_api: url: "https://???:7071" ## HTTP basic authentication. #basic_auth: #username: "???" #password: "???" ## The CLI uses a client configuration to identify who is sending to the StackState instance. The client ## is used to send topology and/or telemetry to the receiver API. ## ## Unless the `--client` argument is passed the CLI will pick the `default` instance as configured below. ## Other clients follow the exact same configuration pattern as the default client. You may simply copy-paste its config and modify whatever is needed. clients: default: api_key: "???" ## The name of the host that is passed to StackState when sending. Leave these values unchanged ## if you have no idea what to fill here. hostname: "hostname" internal_hostname: "internal_hostname"
conf.yaml can hold multiple configurations. The example only holds a
default instance. Other instances can be added on the same level as the default. To use a non default instance use
sts --instance <instance_name> ...
instances: default: base_api: ... clients: ... Preproduction: base_api: ... clients: ...
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. To list all configuration nodes of a type call
sts graph list <type>.
Some well known configuration nodes are:
It may be handy to write configurations to disk. For example, to write all check function to disk call:
sts graph list --ids CheckFunction | xargs sts graph export --ids > mycheckfunctions.stj
To import these check functions call:
sts graph import < mycheckfunctions.stj
sts topic list to list all Kafka topics active for a StackState instance. Then use
sts topic show <topic> to inspect a topic.
To inspect both topology and telemetry a script can be executed with the
sts script command.
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 some test topology or telemetry to StackState.
sts metrics send -h
sts events send -h
sts topology send -h().
To send metrics the cli provides
sts metrics send <MetricName> <OptionalNumberValue> with some predefined settings. Running without any optional arguments sends one datapoint of the given value.
Using optional arguments provides a way to create historical data for a test metric.
-p gives the option to specify a time period. this can be done in weeks
<num>m and seconds
<num>s. or any combination thereof. for example:
-b provides a bandwidth between which the values will be generated. for example:
By default a metrics pattern is random or when a value is provided a flatline. This can be changed by using a pattern argument. The options are
--linearcreates a line between the values given for
-b. plotted over the time given for
--baselinecreates a daily usage curve. On Saturday and Sunday the metric is much lower than on weekdays. The min and max of the curve is set by
-band the time period by
--csvreads a cvs file from the stdin and sends it to stacks state. The content of the csv file should bve
To see all options that are available use
sts metrics send -h.
The cli can send events using
sts events send <eventName> It will send one event with the given name.
please refer to
usage.md provided with the cli for detailed instructions
It is possible to execute scripts using the cli. Use
sts script to execute a script.