RIAK-DEBUG(1)()

NAME
riak-debug - Gather info from a Riak node for troubleshooting.

SYNOPSIS
riak-debug [-c] [-l] [-r] [-s] [-e] [FILENAME | -]

DESCRIPTION
Collect information about a node to aid in diagnosing problems.

By default, riak-debug will gather Riak configuration information, Riak logs, the output of select Riak commands, and the output of select system commands. The results are then written to NODENAME-riak-debug.tar.gz in the current directory. If NODENAME cannot be determined from vm.args, then `hostname`-riak-debug.tar.gz will be used instead.

While collecting information, status output will be printed to standard error. Each '.' printed indicates a command that returned 0 or some other type of successful progress. Each 'E' printed indicates a command that returned nonzero status or some other type of failure. If output is to a file and not to standard out, then once all information has been gathered the filename of the file written is also printed to standard error.

FILENAME may be specified as -, so standard out is reserved for the output of all gathered information in tar.gz format. This is done to make it easy to ship output to a local workstation (see EXAMPLES).

Note that riak-debug is just a shell script provided for convenience and automation, and will run with whatever privileges the executing user may have. The use of sudo or su in various forms may or may not be needed depending on the information that is desired and the operating environment's security practices.

OPTIONS

-c, --cfgs
    Gather Riak configuration information.

-l, --logs
    Gather Riak logs.

-r, --riakcmds
    Gather Riak information and command output.

-s, --syscmds
    Gather general system commands.

-e, --extracmds
    Gather extra command output. These commands are too intense to run on nodes in a cluster in rapid succession, but may be run infrequently on one node.

FILENAME
    Output filename for the tar.gz archive. Use - to specify stdout.

EXAMPLES
In all cases below, work is done in TMPDIR or /tmp, and tar zxf filename.tar.gz or NODENAME-riak-debug.tar.gz will result in creating the directory NODENAME-riak-debug.
    [riak-node]$ riak-debug
Run riak-debug with all default options to gather Riak configuration files, Riak logs, select Riak command output, and select system command output, writing output to NODENAME-riak-debug.tar.gz in the current directory.
    [riak-node]$ riak-debug -r -e /path/to/filename.tar.gz
Run riak-debug with options to gather Riak command output and extra Riak command output, writing output to /path/to/filename.tar.gz.
    [riak-node]$ riak-debug -l - > /path/to/filename.tar.gz
Run riak-debug with the option to gather Riak logs, writing tar.gz data to stdout which is redirected to the specified filename.tar.gz.
    [riak-node]$ APP_EPATH=/opt/riak-debug/app_epath.sh \
                 RIAK_BASE_DIR=/usr \
                 RIAK_BIN_DIR=/usr/sbin \
                 RIAK_ETC_DIR=/etc/riak \
                 /opt/riak-debug/riak-debug
Use environment variables to explicitly specify where to source app_epath.sh, the Riak base path, and the Riak configuration path. This can be useful when running riak-debug on a node with an older version of Riak that did not come with riak-debug.
    [workstation]$ ssh riak-node 'riak-debug -l -' > filename.tar.gz
From a local workstation, SSH to the remote machine riak-node and run riak-debug with the log gathering option, writing tar.gz data to stdout back over SSH to filename.tar.gz on the local workstation.
    [workstation]$ ssh -t node-1 'sudo riak-debug node-1.tar.gz'
    [workstation]$ scp node-1:node-1.tar.gz .
From a local workstation, SSH to the remote machine node-1 and run riak-debug using sudo with default options, writing output to node-1.tar.gz on node-1. Then scp the resulting output file to the local workstation. Note that the use of sudo over SSH requires the -t option to ssh to force pseudo-tty allocation so that passwords are not echoed. Also note that when using a pseudo-tty with ssh, sudo, and riak-debug in this manner that riak-debug will be unable to output to stdout properly, so - cannot be used as the filename.
    [workstation]$ ssh node-1 'sudo riak-debug -c -l -r -s -e -' > node-1.tar.gz
    [workstation]$ for i in 2 3 4 5; do ssh riak-node-${i} 'sudo riak-debug -' > node-${i}; done
From a local workstation, first SSH to the remote Riak node riak-node-1 and run riak-debug with options to gather all possible information, including extra commands, writing tar.gz data to stdout back over SSH to node-1.tar.gz on the local workstation. Then, SSH to four other remote Riak nodes in a loop and run riak-debug with default options, writing four more output files on the local workstation. In this case, sudo may be used and riak-debug may write to stdout provided that the user accounts on the remote machines have been configured so that the user may execute riak-debug without being required to provide a password (NOPASSWD).

ENVIRONMENT
The following environment variables affect the execution of riak-debug. None of the variables are required for typical use of riak-debug. The variables are intended to allow users of older versions of Riak to deploy riak-debug onto their nodes without needing to edit the script to make it work.

TMPDIR
    Directory where riak-debug should temporarily output information. If TMPDIR is not defined, /tmp will be used.

APP_EPATH
    Absolute path to app_epath.sh, which is required when gathering Riak related information.

RIAK_BASE_DIR
    Absolute path to the Riak base directory. This directory should contain the bin or sbin directory that contains the riak and riak-admin commands. It is used to aid in locating directories that are specified in the app.config using relative paths.

RIAK_BIN_DIR
    Absolute path to the directory containing the riak and riak-admin commands. Providing this path allows riak-debug to locate Riak commands without relying on the PATH environment variable.

RIAK_ETC_DIR
    Absolute path to the directory containing app.config and vm.args files.

AUTHORS
Riak is developed by Basho Technologies, Inc. http://basho.com