Heroic Shell is the administration tool of heroic.
An heroic instance can be configured to listen for shell connections. This will allow an administrator to connect and run tasks on the server.
Tasks are small actions indended to help an administrator manage the heroic instances.
You can configure an heroic instance to enable local shell connections by adding the following snippet to your heroic.yml.
shellServer: {}
The shell can be run in two different modes; remote, and standalone. It is also possible to activate profiles, which effects the configuration of the service.
In remote mode, you connect to an already running heroic instance which is configured to accept shell connection.
In standalone mode, you can setup a new heroic instance on-the-fly with a given configuration. The shell will then be connected to that instance, as-if you were running in remote mode.
The shell can be started using the com.spotify.heroic.HeroicShell class.
Assuming you have heroic in your class path, the following is an example of how to do that.
$ java com.spotify.heroic.HeroicShell --help
From now on we will be referring to starting the shell from the heroic project directory, which includes the helper script tools/heroic-shell.
Assuming you are in the heroic project directory, you can invoke the shell like the following.
$ tools/heroic-shell --connect <host>[:port]
At this point you should be connected to the heroic instance, and can invoke any tasks available in it.
Standalone shells includes the heroic service running in the background and the shell is directly connected to this instance. This is typically useful when trying out specific heroic features, specifically in combination with the memory profile
Profiles are small pieces of configuration which can be activated with the -P <name> switch.
Extra options can be passed into profiles using the -X <option>[=<value>] switch.
All available set of profiles and options can be found by at the end of the help command (--help).
$ tools/heroic-shell --help
... skip documentation about switches
Available Extra Parameters:
configure
Automatically configure all backends.
datastax.configure
Automatically configure the datastax backend
elasticsearch.configure
Automatically configure the Elasticsearch backend
elasticsearch.configure
Automatically configure the Elasticsearch backend
Available Profiles (activate with: -P <profile>):
generated - Configures a metric backend containing generated data (does
not support writes)
memory - Configures in-memory backends for everything (useful for
integration/performance testing)
cassandra - Configures a metric backend for Cassandra
cassandra.type=<type>
Type of backend to use, the only valid value is ng
cassandra.seeds=<host>[:<port>][,..]
Seeds to use when configuring backend
The memory profile is special, since it configures a complete service instance in memory. It's a great way for testing out heroic. You can start the memory profile with the following command.
$ tools/heroic-shell --server -P memory -X configure
--server means that the shell will start heroic in server mode, which will accept http requests on port 8080.
-X configure will cause all backends to be automatically configured, saving you the need to do it yourself with the configure task.