This chapter of the user guide discusses the Rose utilities for controlling and monitoring Rose/cylc suites.
If you have been following this user guide, you will
have used the rose suite-run command in
previous chapters. In normal usage, the command sets up
the environment of a Rose/cylc suite, installs and runs
it. We shall discuss the detail in this section.
See Rose Reference Guide: CLI > rose suite-run for a full command reference.
See Rose Reference Guide: Configuration > Configuration Format for more information on the Rose configuration format.
See Rose Reference Guide: Configuration > Suite Configuration for more information on how to set up a Rose suite configuration.
The main functionality of rose
suite-run is to install a suite from the
configuration directory to its runtime location.
--config=DIR
or -C DIR option of the rose
suite-run command.--name=NAME or -n NAME
option of the rose suite-run command.
The same runtime location allows users to be able to
easily look for their installed suites. It also
allows for simple logic in Rose. However, Rose allows
the actual root location of each
$HOME/cylc-run/$NAME/ to be configured to
suit the need for sites or users, which may have very
little disk space in $HOME. In which case,
$HOME/cylc-run/$NAME would become a
symbolic link to the actual physical location. We'll
discuss this functionality in more detail later in
this section.What does rose suite-run install in the
runtime location? Here is a list:
--define=[SECTION]NAME=VALUE.svn info, svn status and
svn diff. If the configuration is a Git
clone, the file would contain the output from
git describe, git status
and git diff.--verbose --verbose (or -v
-v) output of the rose suite-run
command.rose suite-run
will cylc register and cylc
validate the suite before creating the runtime
directory structure and mirroring its items to these
alternate host.rose suite-clean. (See
Configuring the
Install Root Locations.)The rose suite-run command will
normally install from the configuration directory into
the runtime location incrementally. N.B. The command
does not remove items that are not in the configuration
directory but exist in the runtime locations.
If incremental mode is not desirable, the
--new or -N option can be
used to remove and re-create all runtime locations.
N.B. the --new option is equivalent to
running rose suite-clean -y && rose
suite-run, so you may want to take extra care
when using this option.
There are times when you only want to install the
suite but not (re-)run it, (e.g. during development,
for analysing its structure, or to modify an
application configuration during runtime, etc), you can
use the --install-only or -i
option or even the --local-install-only or
-l option. The former will stop after
validating the suite and installing it to the task
hosts. The latter will stop after validating the
suite.
Environment variables defined in the
[env] section of the
rose-suite.conf file are exported to the
environment before the [file:*] and
[jinja2:*] sections of the
rose-suite.conf file are processed, and
before cylc run|restart|reload is
invoked.
Settings defined in each [jinja2:FILE] section of the rose-suite.conf file are added to the header of the named FILE at installation time. The main use of this functionality is to modify the behaviour of cylc's suite.rc file with settings in the [jinja2:suite.rc] section at installation time.
In addition, the following settings are automatically exported to the environment and added to the [jinja2:suite.rc] section.
rose
suite-run command was invoked.For example, if we add the following settings to rose-suite.conf:
[jinja2:suite.rc] HELLO="Greeting" WORLDS=["Earth", "Moon", "Mars"]
then the following example header will be added to the suite.rc file:
#!jinja2
{# Rose Configuration Insertion: Init #}
{% set CYLC_VERSION="5.4.5" %}
{% set HELLO="Greeting" %}
{% set ROSE_ORIG_HOST="alien" %}
{% set ROSE_VERSION="2013-12" %}
{% set WORLDS=["Earth", "Moon", "Mars"] %}
{# Rose Configuration Insertion: Done #}
The rose suite-run command has 3 run
modes: run (default), restart and reload. The mode can
be specified using the command line options
--run=reload|restart|run,
--restart or --reload.
In run and restart modes, rose
suite-run checks that the suite is not already
running on localhost and/or any suite hosts
defined in the lists in the hosts and
scan-hosts settings in the
[rose-suite-run] section of the site/user
configuration. In reload mode, it does the opposite,
ensuring that the suite is already running on one of
these hosts.
In run and restart mode, rose suite-run
will ensure that the suite is registered with cylc. In
all modes, it will then attempt to validate cylc's
suite.rc file using cylc validate
--strict. The --no-strict option
can be used to switch off the --strict
option to cylc validate.
Once the suite.rc file has been
validated, rose suite-run will invoke
cylc run, cylc restart or
cylc reload. For run and restart mode, if
the hosts setting in the
[rose-suite-run] section in the site/user
configuration is defined, rose suite-run
will select a host according to the defined selection
criteria to invoke cylc run|restart. In
reload mode, rose suite-run will invoke
cylc reload on the same host where the
suite is still running.
If you need to pass extra options and arguments to
the cylc run|restart|reload command, you
can specify them on the command line like this:
rose suite-run -- --mode=simulation
In this example, --mode=simulation will
be passed to cylc run.
On success, rose suite-run will launch
the cylc gui to connect to the suite,
unless the --no-gcontrol option is
specified or the DISPLAY environment
variable is not defined.
In normal run mode, rose suite-run will
create a log.DATETIME/ directory in the
runtime location, and (re-)create the symbolic link
log to point to it. The
log.DATETIME/ directory from previous runs
will then be compressed into a Tar-Gzip archive
log.DATETIME.tar.gz, unless the
--no-log-archive option is specified or if
it is being pointed to by a symbolic link matching the
glob log.* in the same directory.
As discussed earlier in Locations, if $HOME/cylc-run/$NAME/ is not a suitable physical location for hosting the suite runtime files, (perhaps the disk does not have enough space or has poor performance), it is possible to configure the root of an alternate physical location using the top level setting root-dir=LIST in the suite's rose-suite.conf or the same setting under the [rose-suite-run] section of the Rose site/user configuration. The LIST should be a newline delimited list of PATTERN=DIR pairs. The PATTERN should be a glob-like pattern for matching a host name. The DIR should be the root directory to install a suite run directory to. E.g.:
In a rose-suite.conf file, it is a top level setting:
[]
root-dir=hpc*=$WORKDIR
=*=$DATADIR
In a site/user configuration file, it is under [rose-suite-run]:
[rose-suite-run]
root-dir=hpc*=$WORKDIR
=*=$DATADIR
In this example, invoking rose
suite-run on a suite with name $NAME
will create ~/cylc-run/$NAME as a symbolic
link to $DATADIR/cylc-run/$NAME/ on any
machine, except those with their hostnames matching
hpc*. For those hosts, it will create
~/cylc-run/$NAME as a symbolic link to
$WORKDIR/cylc-run/$NAME/.
In addition to the main suite directory, the share/, share/cycle/ and work/ sub-directories can also be configured using the settings root-dir{share}, root-dir{share/cycle}, and root-dir{work} respectively.
Rose Bush presents the logs of your running or completed suites and the logs of their task jobs (e.g. STDOUT or STDERR) via a web interface. If Rose Bush is not already configured at your site, see Rose: Installation > Configuring Rose Bush on how to configure it. If you do not have the authority to do so, you should still be able to start an ad-hoc Rose Bush web server by typing:
/path/to/rose/bin/rose bush start [PORT]
If [PORT] is not specified, the default is 8080.
Once configured (or you have started an ad-hoc
server), typing rose suite-log in a suite
directory will launch Rose Bush on your web
browser.
You can use Rose Bush to:
Remember Rose Bush is not a monitoring tool,
cylc gscan and cylc gpanel
are designed for this and provide interactive tools to
monitor and interrogate your suites. Rose Bush has been
designed to view any suite provided it has access to
the $HOME/cylc-run/ directory of a user. It
also provides an aesthetically pleasing and user
friendly web view of the suites files including:
It allows you to filter the Display Options using the tool provided in a drop down section for example by Task names globs, Cycle globs, etc or by cycles list or jobs list.
To invoke Rose Bush in the suite directory: E.g.:
rose suite-log
or
rose slv
Invoking this command launches a web browser to display the logs of a running or stopped suite in Rose Bush.
If run with the --update option this synchronises logs between the various filesystems that the suite has run jobs on and the suite host. This is useful if cylc has been unable to retrieve a log on job completion.
See Rose Reference Guide: CLI > rose suite-log for more information.
Or rose sgc. A convenient way to launch
cylc gui. In the absence of arguments, the
command assumes that the base name of the current
directory is the name of the suite you want to launch
cylc gui on.
See Rose Reference Guide: CLI > rose suite-gcontrol for more information.
A wrapper of cylc scan. The command
scans for your running suites in the dedicated suite
hosts as specified by the Rose site/user
configuration.
See Rose Reference Guide: CLI > rose suite-scan for more information.
Or rose suite-stop. A convenient way to
run cylc shutdown. In the absence of
arguments, the command assumes that the base name of
the current directory is the name of the suite you want
to run cylc shutdown on. If your suite is
running on a dedicated suite host as specified by the
Rose site/user configuration, it will automatically
connect to the suite at the correct host.
See Rose Reference Guide: CLI > rose suite-shutdown for more information.
This command correctly removes items created by rose suite-run, including items on task job hosts and actual run locations under alternate disks. In the absence of arguments, the command assumes that base name of the current directory is the name of the suite you want to clean. It checks that the suite is not running before doing any removal.
See Rose Reference Guide: CLI > rose suite-clean for more information.