Amygdala CLI

The amygdala command currently only has a single sub-command (other than help for displaying usage instructions and completions for shell support), but is intended to prevent breaking changes being required when additional commands are added (for instance if an interactive config file generator is added).

$ amygdala --help
Usage: amygdala <COMMAND>

Commands:
  serve        Start the launcher process, listening for commands via gRPC
  completions  Generate shell completions for amygdala
  help         Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

Serve

The serve subcommand starts the launcher in the foreground listening for incoming requests from the gda client.

It is possible to run amygdala with no further options or arguments if the defaults are acceptable, but the following configuration is available.

$ amygdala serve --help
Start the launcher process, listening for commands via gRPC

Usage: amygdala serve [OPTIONS]

Options:
  -c, --config <CONFIG>
          Configuration file for the GDA launcher
          
          If not present the config file will be read from the first defined of
          the following:
          * $AMYGDALA_CONFIG
          * $XDG_CONFIG_HOME/amygdala/config.toml
          * $HOME/.config/amygdala/config.toml

  -p, --port <PORT>
          Port opened for gRPC requests
          
          [default: 50051]

  -h, --help
          Print help (see a summary with '-h')

Terminal Logging:
  -v, --verbose...
          Increase the level of logs written to stderr

  -q, --quiet
          Disable all output to stderr/stdout

File Logging:
  -l, --log-directory <LOG_DIRECTORY>
          Parent directory of log files written by the amygdala process (not
          those written by the GDA processes it launches)
          
          If not present, logging will not be written to file.

  -L, --level <LEVEL>
          Level threshold of logs that should be sent to file

Graylog:
      --graylog <FILE>
          Configuration file containing graylog host and port if not passed
          individually

      --graylog-host <GRAYLOG_HOST>
          Hostname of graylog server

      --graylog-port <GRAYLOG_PORT>
          Port of graylog server

General options

--config/-c

$ amygdala serve --config path/to/config.toml

The file used to configure how the GDA processes are started and managed can be set via the --config/-c option. If this is not given, the file is read from the first of the following to be defined.

• $AMYGDALA_CONFIG environment variable.
• $XDG_CONFIG_HOME/amygdala/config.toml
• $HOME/.config/amygdala/config.toml

Note that if one of these is defined (the environment variable is set), the subsequent files are not checked, even if the file is not found.

Port

$ amygdala serve --port 9876

The port which should be opened for the gRPC end points and to which the gda client should connect.

This defaults to the same 50051 that the client defaults to so both should be changed if either of them are.

Logging

By default, minimal logging (info level and above) is written to stdout, no log files are written and no messages are sent to graylog.

Terminal Logging

The level of logging that is written to stdout can be adjusted using -v/--verbose flags. These can be repeated to increase logging to debug and then to trace. Repeating further has no effect.

If no logs are required, -q/--quiet can be used to remove all terminal output.

File Logging

-l/--log-directory

If a log directory is given, the logs will be written to file named gda_launcher.yyyy-mm-dd.log in that directory. A new date-stamped file is created each day and will be kept for 2 weeks.

$ amygdala serve --log-directory /path/to/logs

-L/--level

The logs written to file can be filtered by level. This should be one of the keywords ERROR, WARN, INFO, DEBUG or TRACE (case insensitive)

If a log file level is set, a log directory is also required (as the level does not make sense is no logs are being written).

By default, logs at debug level and above are written to file (if a log directory is set).

$ amygdala serve -L TRACE # --log-directory also required if setting level

Graylog

Log events can also be sent to a central Graylog instance. For this a host name and port are required. The graylog server should be configured to accept TCP connections (instead of UDP). The host name should not include any schema or protocol information, eg graylog.example.com instead of tcp://graylog.example.com or similar.

There are two ways of passing graylog configuration.

External File

If the host and port are written in TOML format to a file, the path to that file can be passed in. This is useful if multiple instances of amygdala should share a common configuration to allow it to be updated in a single place if required.

This file can be passed in using the --graylog option.

$ amygdala serve --graylog /path/to/graylog.toml

The file should have the format

host = "graylog.example.com"
port = 12345

Individual Fields

The host and port can also be passed directly. In this case both are required.

$ amygdala serve --graylog-host graylog.example.com --graylog-port 12345

It is not possible to use these field to override a value from an external graylog config file.