November 07, 2017
by Tomaz Muraus
StackStorm v2.5.0 has been released recently. In addition to Inquiries, it includes another widely requested feature – real-time output of actions.
Real-time action output streaming allows users to see any output produced by an action in real-time.
This makes troubleshooting and debugging actions much easier and faster. It is especially handy in environments where StackStorm is used as a CI / CD tool and for long running actions (do you have a long running action which builds and installs a software package and you want to see the progress in real-time? Now that and a lot more is possible).
Prior to this release, it was only possible to see the output once the action has finished (well, there were some workarounds which involved using “tail” command, but those workarounds had many limitations and issues).
We have done a lot of testing of this feature, but it is still considered experimental in this release and as such, it’s behind a feature flag. To enable it, set actionrunner.stream_output = True property in st2.conf and restart all services (sudo st2ctl restart).
Pending no major issues or blockers, the streaming feature will be enabled by default in the next major release.
Right now the feature is supported for all the most commonly used runners (local, remote, python runner).
Immediately after the action execution has been scheduled you can start consuming the output either by using the CLI or API:
We have added a new “st2 execution tail” command. This command consumes events from the event-stream API and prints any output as soon as it’s available.
st2 execution tail <execution id> [–include-metadata] [–type=stdout/stderr]
The command also supports simple workflows which are not nested – it will automatically follow any new action which which is kicked off by the workflow and tail and print the output of it.
The video above shows an example of this command in action. In this example we ran the “packs.install” action and then tailed the output of it. As you can see, we did not provide an “execution id” argument to the command. By default, if no execution id argument is provided, it will default to “last” and tail the last execution in the system.
In addition to the CLI, you can consume the output using the new GET /v1/executions/<execution id>/output[?type=stdout/stderr/other] API endpoint.
This is useful in situations when you might not have access to the CLI and when you want to consume the output quickly and easily. The API endpoint keeps a long running connection open until the execution completes (or until the user closes the connection) which means you can simply curl the URL and any output will be shown as soon as it’s available.
If you want to access the output programmatically, the best way to do that is using the event-stream API endpoint. Event-stream API endpoint follows the server-sent event specification and any change which is made to a StackStorm resource is reflected in the event-stream (e.g. an event is dispatched when an execution has been scheduled, when it starts running, when it completes, etc.).
The name of the event for the action output events is st2.execution.output__create.
Right now real-time output is only available via CLI and the API. We plan to add support for it to the WebUI in future, once the feature comes out of the experimental phase.
We are excited and happy to finally be able to bring you this widely requested feature. We encourage you to try it out and as always, if you have any questions / comments / feedback, please get in touch.
This post served as a brief introduction. For more information and more in-depth examples, please refer to the documentation – Real-time Action Output Streaming. If you are interested in the implementation details and want to dig deeper, the following PRs should serve as a good starting point – 3657, 3729.