yb_stats version option
Tags: yugabytedb, observability, rust
Published: 2022-12-15 16:06:56

This is a blogpost about the open source [yb_stats](https://github.com/fritshoogland-yugabyte/yb_stats.git) tool for [YugabyteDB](https://yugabyte.com) 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: ```shell
% 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: ```shell
% 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: ```shell
% 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.