yb_stats version option

This is a blogpost about the open source yb_stats tool for YugabyteDB to look into the database endpoints versions. There are multiple options to look at the versions of the Yugabyte database components.

In order to use yb_stats tool, you have to specify the ip addresses and ports for the http endpoints of the YugabyteDB processes, along with the node_exporter port number, if node_exporter is in use. When that is done, yb_stats will write a file with the name of .env to the current working directory which specifies these, which it can reuse when it's executed again.

How is the version obtained?

The version of YugabyteDB is obtained from the /api/v1/version path of an endpoint.

How do I use version information with yb_stats?

Version information is used in the following situations:

1. When yb_stats is invoked with --print-version without a snapshot number.
   In this situation yb_stats uses either the hosts addresses and ports set with --hosts and --ports, the hosts and ports set in .env or the default values. The version information is directly obtained from the hosts, and thus requires direct network access. For example:
   

   % yb_stats --print-version
   hostname_port        version_number  build_nr   build_type build_timestamp          git_hash
   192.168.66.82:9000   2.17.0.0        24         RELEASE    16 Nov 2022 00:21:52 UTC d4f01a5e26b168585e59f9c1a95766ffdd9655b1
   192.168.66.82:7000   2.17.0.0        24         RELEASE    16 Nov 2022 00:21:52 UTC d4f01a5e26b168585e59f9c1a95766ffdd9655b1
   192.168.66.81:9000   2.17.0.0        24         RELEASE    16 Nov 2022 00:21:52 UTC d4f01a5e26b168585e59f9c1a95766ffdd9655b1
   192.168.66.81:7000   2.17.0.0        24         RELEASE    16 Nov 2022 00:21:52 UTC d4f01a5e26b168585e59f9c1a95766ffdd9655b1
   192.168.66.80:9000   2.17.0.0        24         RELEASE    16 Nov 2022 00:21:52 UTC d4f01a5e26b168585e59f9c1a95766ffdd9655b1
   192.168.66.80:7000   2.17.0.0        24         RELEASE    16 Nov 2022 00:21:52 UTC d4f01a5e26b168585e59f9c1a95766ffdd9655b1
   

2. When yb_stats is invoked with --print-version with a snapshot number.
   In this situation yb_stats requires snapshots to be available in the current working directory, and the set snapshot number to be available. The version information is read from the information in the snapshot, and does not require the hosts to be available. For example:
   

   % yb_stats --print-version 0
   hostname_port        version_number  build_nr   build_type build_timestamp          git_hash
   192.168.66.82:9000   2.15.3.2        1          RELEASE    04 Nov 2022 16:53:01 UTC 5ef608b43a994ab03a12ed3359258ec156d04a14
   192.168.66.82:7000   2.15.3.2        1          RELEASE    04 Nov 2022 16:53:01 UTC 5ef608b43a994ab03a12ed3359258ec156d04a14
   192.168.66.81:9000   2.15.3.2        1          RELEASE    04 Nov 2022 16:53:01 UTC 5ef608b43a994ab03a12ed3359258ec156d04a14
   192.168.66.81:7000   2.15.3.2        1          RELEASE    04 Nov 2022 16:53:01 UTC 5ef608b43a994ab03a12ed3359258ec156d04a14
   192.168.66.80:9000   2.15.3.2        1          RELEASE    04 Nov 2022 16:53:01 UTC 5ef608b43a994ab03a12ed3359258ec156d04a14
   192.168.66.80:7000   2.15.3.2        1          RELEASE    04 Nov 2022 16:53:01 UTC 5ef608b43a994ab03a12ed3359258ec156d04a14
   

3. When yb_stats is invoked with no option is specified, which means 'adhoc in-memory diff'.
   In this situation yb_stats uses either the hosts addresses and ports set with --hosts and --ports, the hosts and ports set in .env or the default values. The version information is fetched from the hosts at begin and end in-memory snapshot time, and thus requires direct network access.
   A version difference is only shown if there is a difference. In normal cases, this should not generate a difference to be reported, unless an endpoint is actually changed from version in between the first and second in-memory snapshot, or an endpoint is added, removed, stopped or started.

4. When yb_stats is invoked with --snapshot-diff.
   In this situation yb_stats requires snapshots to be available in the current working directory, and the snapshot numbers requested for the diff, and does not require the hosts to be available. The version diff is shown along with all the other information that is diffed. A version difference is only shown if there is a difference.
   In general, trying to perform a snapshot-diff at YugabyteDB endpoints that have restarted will lead to invalid statistics for counters and undefined behaviour. The addition of the version change check is just to be absolutely sure to see everything that potentially might happen.

5. When yb_stats is invoked with --versions-diff.[1]
   In this situation yb_stats requires snapshots to be available in the current working directory, and the snapshot numbers requested for the diff, and does not require the hosts to be available. The version diff is the only thing shown, and does not show anything if there is no difference. To see if there has been a version change or other endpoint change, you can use --versions-diff. For example:
   

   % yb_stats --versions-diff
   0 2022-12-15 14:26:14.234381 +01:00
   1 2022-12-15 14:32:46.193290 +01:00
   2 2022-12-15 16:54:54.901797 +01:00
   Enter begin snapshot: 0
   Enter end snapshot: 2
   * 192.168.66.80:7000   Versions: 2.15.3.2->2.17.0.0 b1->b24 RELEASE 04 Nov 2022 16:53:01 UTC->16 Nov 2022 00:21:52 UTC 5ef608b43a994ab03a12ed3359258ec156d04a14->d4f01a5e26b168585e59f9c1a95766ffdd9655b1
   - 192.168.66.80:9000   Versions: 2.15.3.2 b1 RELEASE 04 Nov 2022 16:53:01 UTC 5ef608b43a994ab03a12ed3359258ec156d04a14
   * 192.168.66.81:7000   Versions: 2.15.3.2->2.17.0.0 b1->b24 RELEASE 04 Nov 2022 16:53:01 UTC->16 Nov 2022 00:21:52 UTC 5ef608b43a994ab03a12ed3359258ec156d04a14->d4f01a5e26b168585e59f9c1a95766ffdd9655b1
   * 192.168.66.81:9000   Versions: 2.15.3.2->2.17.0.0 b1->b24 RELEASE 04 Nov 2022 16:53:01 UTC->16 Nov 2022 00:21:52 UTC 5ef608b43a994ab03a12ed3359258ec156d04a14->d4f01a5e26b168585e59f9c1a95766ffdd9655b1
   * 192.168.66.82:7000   Versions: 2.15.3.2->2.17.0.0 b1->b24 RELEASE 04 Nov 2022 16:53:01 UTC->16 Nov 2022 00:21:52 UTC 5ef608b43a994ab03a12ed3359258ec156d04a14->d4f01a5e26b168585e59f9c1a95766ffdd9655b1
   * 192.168.66.82:9000   Versions: 2.15.3.2->2.17.0.0 b1->b24 RELEASE 04 Nov 2022 16:53:01 UTC->16 Nov 2022 00:21:52 UTC 5ef608b43a994ab03a12ed3359258ec156d04a14->d4f01a5e26b168585e59f9c1a95766ffdd9655b1
   

   
   In the above case the versions for all endpoints changed from version 2.15.3.2 to 2.17.0.0, except for endpoint 192.168.66.80:9000, which was removed ('-').

6. When yb_stats is invoked with --snapshot.
   In this situation yb_stats requires either the hosts addresses and the ports set with --hosts and --ports, the hosts and ports set in .env or the default values. The version information is fetched from the hosts for the snapshot. The snapshot mode does not show anything, it only stores the information in the snapshot that it creates.
   With --snapshot nothing is shown, but the version information for all available endpoints is gathered and saved.

Filtering

With clusters with higher number of nodes and YugabyteDB processes, it can be beneficial to filter for specific hosts or ports to reduce the amount of data and remove hosts or ports that are not needed for the query or investigation.

[1] Available with yb_stats version 0.8.10.