ybrelay Options

The ybrelay service can run without options; however, many options are available, as described in this section.

A simple start command would identify the work directory (-w or --workdir option):
$ ybrelay -w ./work
14:23:34.123 [ INFO] ABOUT CLIENT:
    app.cli_args         = "-w" "./work"
    app.name_and_version = "Yellowbrick Data Relay version 3.1.0-616"
    java.home            = "/usr/lib/jvm/java-8-oracle/jre"
    java.version         = "1.8.0_101"
    jvm.memory           = "491.00 MB (max=7.11 GB)"
    jvm.name_and_version = "Java HotSpot(TM) 64-Bit Server VM (build 25.101-b13, mixed mode)"
    jvm.options          = "-Xms512m, -Xmx8g, -ea, -Dapp.name=ybrelay, -Dapp.pid=11403, -Dapp.repo=/opt/ybtools/3.1.0.616/lib, -Dapp.home=/opt/ybtools/3.1.0.616, -Dbasedir=/opt/ybtools/3.1.0.616"
    jvm.vendor           = "Oracle Corporation"
    os.name_and_version  = "Linux 4.4.0-31-generic (amd64)"

14:23:34.125 [ INFO] Yellowbrick log level: DEBUG
...

Startup options may be specified in the ybrelay.options file.

Contents of the ybrelay.options File

The default ybrelay.options file, found in the /opt/ybtools/<version>/config directory, contains the following entries:
--workdir
/var/lib/ybrelay/work
--logdir
/var/log/ybrelay/logs
--log-level
WARN
--logfile
/var/log/ybrelay/ybrelay.log
--logfile-log-level
DEBUG
--logfile-backups
10
--logfile-size
10MB

The options in the file are defined in the following sections.

Common Options

The following ybrelay options are common to several ybtools clients.
@file
Specify a file that includes a set of ybrelay options and values to use. Options in the file must be specified in the following form (using separate lines for each option name and value):
option1
  value for option1
  option2
  value for option2
  ...
-?, --help, --help-advanced
Return basic (or advanced) usage information for the ybrelay command and its options.
--java-version
Return the Java version that is running on the client system. The client tools require the 64-bit version of Java 8 (also known as Java 1.8). Java 9 and 10 are not supported.
--log-level
Specify the logging level for the default console output. The default level is WARN. (Use the --logfile-log-level option to specify the logging level for a named log file.)

Using the default WARN setting reduces the logs that ybrelay writes to stderr.

--logfile
Specify the name and location of a log file for ybrelay operations. If the specified file already exists, it will be truncated. If this option is not specified, no log file is written. When you specify this --logfile option, also specify a --logfile-log-level value other than OFF.
--logfile-log-level
Specify the logging level for a given log file (as defined with the --logfile option). If the level is not specified, it defaults to the --log-level value. You must specify a --logfile-log-level value other than OFF when you specify the --logfile option.
-q, --quiet
Do not write any output to the console. If --quiet is specified, you must also specify --logfile.
--version
Display the version of ybrelay you are running (as part of ybtools). This option is not intended to be combined with other options. For example:
$ ybrelay --version
Yellowbrick Data Relay version 3.1.0-616

ybrelay Options

The following options are specific to the ybrelay service.

--address STRING, -a STRING
Listen address. Default: 0.0.0.0.
--connection-timeout-seconds NUMBER
Connection timeout (in seconds). Default: 120.
--idle-timeout NUMBER
Detect idle timeout for aborted loads (in minutes). Default: 5
--logdir STRING, -l STRING
Specify a path where log data is created and managed. Default: /var/lib/ybrelay/work.
--logfile-backups NUMBER
Set the maximum number of log file backups. Default: 10. The ybrelay.log file is managed with the --logfile-backups and --logfile-size values, which set the rotation policies for this log file.
--logfile-size STRING
Set the maximum log file size. Default: 100MB.
--log-retention-days NUMBER
Set the number of days to retain stored log files (in /var/log/ybrelay/logs or the specified logdir). Default: 14. This directory can grow large if a large number of ybload logs are generated. For example, if ybrelay is running a distinct ybload operation every minute, at least 2880 files are generated daily.
--port NUMBER, -p NUMBER
Listen port. Default: 21212.
--queuesizebytes NUMBER, -s NUMBER
Set the queue size, in bytes (per load job). Default: 536870912.
--read-timeout-seconds NUMBER
Set the read timeout (in seconds). Default: 0.
--tasks NUMBER, -t NUMBER
Set the task count (for parallelism). Default: 4.
--workdir STRING, -w STRING
Set the path to create and manage temporary data. Default: /var/lib/ybrelay/work.
--write-timeout-seconds NUMBER
Set the write timeout (in seconds). Default: 0.
--ybload STRING, -y STRING
Set the path to the ybload client.
--ybload-args STRING
Set the default arguments to ybload. Default:
--no-trim-white --log-level WARN --logfile-log-level DEBUG
--ybload-vmargs STRING
Set VM arguments to ybload (if --ybload path is not used).

Advanced Options

The following options are specific to the ybrelay service.

--jmx-address STRING
JMX listen address. This option is used by a tool or program to establish a JMX connection. Default: 0.0.0.0
--jmx-port NUMBER
JMX listen port. This option must be set to a non-zero number to enable remote access. Default: 0
For remote connections, the JMX URL uses the following pattern:
service:jmx:rmi:///jndi/rmi://${ybrelay-hostname}:9000/relay

where ${ybrelay-hostname} is your hostname where the ybrelay service is running.

By default, the ybrelay systemd service configures the --jmx-port to be 9000, which is used to programmatically establish a JMX connection with the relay to access the following JMX options:
  • Main attributes to the JMX MBean:
    • ConnectedClientCount
    • ActiveJobCount
    • ProcessedJobCount
  • Metrics for diagnostics:
    • io.yellowbrick.relay:name=relay-server Relay service primary management interface and attributes
    • io.yellowbrick.relay:name=relay-load-started Guage of relay load start events
    • io.yellowbrick.relay:name=relay-load-committed Guage of relay load commit events
    • io.yellowbrick.relay:name=relay-load-aborted Guage of relay load abort events
    • io.yellowbrick.relay:name=relay-node-start Guage of relay remote client node start events
    • io.yellowbrick.relay:name=relay-node-stop Guage of relay remote client node stop events
    • io.yellowbrick.relay:name=relay-node-data-packets Guage of relay remote client node data packet events
  • Histogram values for tracking data compression rates:
    • io.yellowbrick.relay:name=relay-node-data-compressed Histogram of relay remote client node data compressed packet size
    • io.yellowbrick.relay:name=relay-node-data-uncompressed Histogram of relay remote client node data uncompressed packet size
    • io.yellowbrick.relay:name=relay-node-data-compression-percent Histogram of relay remote client node data compression ratio