Environment

• YugabyteDB - All Versions

Issue

Occasionally, the support or development teams may request that you use the Yugatool utility to perform certain tasks. For example, this utility has the ability to generate reports that can assist with analysis of consensus or table state issues in a YugabyteDB Universe. This article provides instructions for common uses of the Yugatool utility.

Resolution

Overview

The Yugatool utility can be used to generate reports. For example:

• A "tablet info" report, showing the information for a specific table shard ("tablet").
• A "cluster info tablet" report (often just called a "tablet report"), showing various information about all the tables and tablets for a database, as well as the tablet servers that are serving them.

In order to generate reports or use other Yugatool functionality, you will need the following information:

• The type of report to run.
• A list of the master addresses for the Universe.
• If TLS has been enabled for the Universe, the path to the CA and client TLS certificates.

Note: The current version of Yugatool as of the publication date of this article is:

$ ./yugatool --version
yugatool version b5033b88a0a0473fa90e3456d84ea54b077426b6

Steps

1. Download the attached yugatool.gz file, copy it to the master leader node (or another Linux system that can reach the master leader of the YugabyteDB Universe), extract it, and mark it executable:

gunzip yugatool.gz
chmod +x yugatool

2. Export the list of master addresses for the Universe as an environment variable for use in later commands. For example:

export MASTERS=10.0.0.1:7100,10.0.1.1:7100,10.0.2.1:7100

Replace the master addresses with the correct master addresses for your Universe. The IP addresses of the masters can be found in the Nodes tab of the YugabyteDB Anywhere (formerly Yugabyte Platform) interface.

If TLS encryption is not enabled for this Universe, skip steps 3 and 4.

3. If TLS encryption is enabled for the Universe, export the paths to the TLS certificates as an environment variable:

export TLS_CONFIG="--cacert /home/yugabyte/.yugabytedb/root.crt \
--client-cert /home/yugabyte/.yugabytedb/yugabytedb.crt \
--client-key /home/yugabyte/.yugabytedb/yugabytedb.key"

Replace the paths to the certificate and key files with the appropriate values if these files are in a non-default location.

If the Universe is using CA-signed certificates, skip step 4.

4. If the Universe is using self-signed TLS certificates, add the --skiphostverification flag to the TLS_CONFIG environment variable:

export TLS_CONFIG="$TLS_CONFIG --skiphostverification"

5. Run Yugatool to generate the requested report. For example, to generate a tablet report and display it at the console:

./yugatool cluster_info \
  -m $MASTERS \
  $TLS_CONFIG \
  --show-tableid \
  --tablet-report
  

To save the report to a file, use a redirect. For example:

./yugatool cluster_info \
-m $MASTERS \
$TLS_CONFIG \
--show-tableid \
--tablet-report \
> /tmp/tablet-report-$(hostname)-$(date +'%F_%H%M%S').out

To generate a report in JSON format, add the -o flag:

./yugatool cluster_info \
  -m $MASTERS \
  $TLS_CONFIG \
  --show-tableid \
  --tablet-report \
  -o json \
  > /tmp/tablet-report-$(hostname)-$(date +'%F_%H%M%S').json

6. Compress the resulting report file:

gzip /tmp/tablet-report-yb-dev-testuniverse-n1-2022-11-01.json

7. Upload the resulting report to your Zendesk ticket.

Commonly Used yugatool Commands

tablet_info

To get detailed information about a specific tablet run the following command:

./yugatool tablet_info <tablet_id> \
-m $MASTERS \
$TLS_CONFIG \
-o json > <tablet_id>.info

Where <tablet_id> is the UUID of a tablet.  For example: 7c6df0b2d2c14bc7947249a1d9c96d01