When working with a distributed SQL database like YugabyteDB, understanding the unique identity of each node in the cluster becomes crucial, especially for debugging, monitoring, and administration. In this tip, we’ll look at how to retrieve the UUID (Universally Unique Identifier) of a YugabyteDB TServer, explain what it is, and demo four different ways to access it.
What Is the TServer UUID?
The TServer UUID is a 128-bit value used to uniquely identify each TServer node in your YugabyteDB cluster. It’s auto-generated by default when a TServer first starts up, and it remains persistent (saved in the instance file on disk) unless explicitly overridden.
Why is it useful?
• It helps distinguish between nodes with similar IPs or hostnames.
• It’s used in system metadata, replication tracking, and internal health checks.
• It plays a role in things like
yb_servers()output, log messages, and CLI tooling.
If needed, you can override this UUID using the instance_uuid_override documentation gFlag.
How to Find the UUID of a TServer
Here are several methods you can use to display the TServer UUID for a node:
1. Query with yb_servers() in ysqlsh
ysqlsh -h 127.0.0.1 -c "SELECT host, uuid, universe_uuid FROM yb_servers();"
Example:
[root@localhost ~]# ysqlsh -h 127.0.0.1 -c "SELECT host, uuid, universe_uuid FROM yb_servers() ORDER BY host;"
host | uuid | universe_uuid
-----------+----------------------------------+--------------------------------------
127.0.0.1 | 6d8f6ec16892464a9f5af6b2c60e2ad9 | 73869a07-aef2-4b89-8b6e-e832cd18f96c
127.0.0.2 | 421f7d6d96e346d48dace2181e4d02c8 | 73869a07-aef2-4b89-8b6e-e832cd18f96c
127.0.0.3 | 3578890add6a4e669284b248cfaf6652 | 73869a07-aef2-4b89-8b6e-e832cd18f96c
(3 rows)
You can also isolate the connected node:
ysqlsh -h 127.0.0.1 -U yugabyte -c "SELECT host, uuid, universe_uuid FROM yb_servers() WHERE host = host(inet_server_addr());"
Example:
[root@localhost ~]# ysqlsh -h 127.0.0.1 -c "SELECT host, uuid, universe_uuid FROM yb_servers() WHERE host = host(inet_server_addr()) ORDER BY host;"
host | uuid | universe_uuid
-----------+----------------------------------+--------------------------------------
127.0.0.1 | 6d8f6ec16892464a9f5af6b2c60e2ad9 | 73869a07-aef2-4b89-8b6e-e832cd18f96c
(1 row)
2. Use yb-ts-cli to Fetch the UUID
If you’re running directly on the server, yb-ts-cli provides a quick way to grab the UUID:
yb-ts-cli --server_address=127.0.0.1 status | grep uuid | sed -n 's/.*"\([a-f0-9]\{32\}\)".*/\1/p'
Example:
[root@localhost ~]# yb-ts-cli --server_address=127.0.0.1 status | grep uuid | sed -n 's/.*"\([a-f0-9]\{32\}\)".*/\1/p'
6d8f6ec16892464a9f5af6b2c60e2ad9
3. Use the TServer HTTP Endpoint
The TServer HTTP endpoint at port 9000 also includes the UUID in its HTML response. You can parse it like this:
curl -s http://127.0.0.1:9000 | sed -n 's/.*server uuid \([a-f0-9]\{32\}\).*/\1/p'
Example:
[root@localhost ~]# curl -s http://127.0.0.1:9000 | sed -n 's/.*server uuid \([a-f0-9]\{32\}\).*/\1/p'
6d8f6ec16892464a9f5af6b2c60e2ad9
This is especially useful when you want a quick peek without accessing the SQL interface or CLI tools.
Bonus: From the instance File (Advanced)
On disk, the UUID is stored in the TServer’s instance metadata file, located in the directory defined by the --fs_data_dirs gFlag (typically ./yb-data/tserver/). While you can extract it using tools like strings or protobuf decoders (which is a pain in the @%*#!), the methods shown above are generally safer and more straightforward.
Have Fun!
