Documentation update of virtual table system_views.clients

patch by Tibor Repasi; reviewed by Berenguer Blasi, Ekaterina Dimitrova for CASSANDRA-17344
apache · Mar 8, 2022 · ac34f28 · ac34f28
1 parent 537d02d
commit ac34f28
Showing 1 changed file with 93 additions and 24 deletions.
diff --git a/doc/modules/cassandra/pages/new/virtualtables.adoc b/doc/modules/cassandra/pages/new/virtualtables.adoc
@@ -109,18 +109,80 @@ We shall discuss some of the virtual tables in more detail next.
 === Clients Virtual Table
 
 The `clients` virtual table lists all active connections (connected
-clients) including their ip address, port, connection stage, driver
+clients) including their ip address, port, client_options, connection stage, driver
 name, driver version, hostname, protocol version, request count, ssl
 enabled, ssl protocol and user name:
 
 ....
-cqlsh:system_views> select * from system_views.clients;
- address   | port  | connection_stage | driver_name | driver_version | hostname  | protocol_version | request_count | ssl_cipher_suite | ssl_enabled | ssl_protocol | username
------------+-------+------------------+-------------+----------------+-----------+------------------+---------------+------------------+-------------+--------------+-----------
- 127.0.0.1 | 50628 |            ready |        null |           null | localhost |                4 |            55 |             null |       False |         null | anonymous
- 127.0.0.1 | 50630 |            ready |        null |           null | localhost |                4 |            70 |             null |       False |         null | anonymous
+cqlsh> EXPAND ON ;
+Now Expanded output is enabled
+cqlsh> SELECT * FROM system_views.clients;
+
+@ Row 1
+------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ address          | 127.0.0.1
+ port             | 50687
+ client_options   | {'CQL_VERSION': '3.4.5', 'DRIVER_NAME': 'DataStax Python Driver', 'DRIVER_VERSION': '3.25.0'}
+ connection_stage | ready
+ driver_name      | DataStax Python Driver
+ driver_version   | 3.25.0
+ hostname         | localhost
+ protocol_version | 5
+ request_count    | 16
+ ssl_cipher_suite | null
+ ssl_enabled      | False
+ ssl_protocol     | null
+ username         | anonymous
+
+@ Row 2
+------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ address          | 127.0.0.1
+ port             | 50688
+ client_options   | {'CQL_VERSION': '3.4.5', 'DRIVER_NAME': 'DataStax Python Driver', 'DRIVER_VERSION': '3.25.0'}
+ connection_stage | ready
+ driver_name      | DataStax Python Driver
+ driver_version   | 3.25.0
+ hostname         | localhost
+ protocol_version | 5
+ request_count    | 4
+ ssl_cipher_suite | null
+ ssl_enabled      | False
+ ssl_protocol     | null
+ username         | anonymous
+
+@ Row 3
+------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ address          | 127.0.0.1
+ port             | 50753
+ client_options   | {'APPLICATION_NAME': 'TestApp', 'APPLICATION_VERSION': '1.0.0', 'CLIENT_ID': '55b3efbd-c56b-469d-8cca-016b860b2f03', 'CQL_VERSION': '3.0.0', 'DRIVER_NAME': 'DataStax Java driver for Apache Cassandra(R)', 'DRIVER_VERSION': '4.13.0'}
+ connection_stage | ready
+ driver_name      | DataStax Java driver for Apache Cassandra(R)
+ driver_version   | 4.13.0
+ hostname         | localhost
+ protocol_version | 5
+ request_count    | 18
+ ssl_cipher_suite | null
+ ssl_enabled      | False
+ ssl_protocol     | null
+ username         | anonymous
+
+@ Row 4
+------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ address          | 127.0.0.1
+ port             | 50755
+ client_options   | {'APPLICATION_NAME': 'TestApp', 'APPLICATION_VERSION': '1.0.0', 'CLIENT_ID': '55b3efbd-c56b-469d-8cca-016b860b2f03', 'CQL_VERSION': '3.0.0', 'DRIVER_NAME': 'DataStax Java driver for Apache Cassandra(R)', 'DRIVER_VERSION': '4.13.0'}
+ connection_stage | ready
+ driver_name      | DataStax Java driver for Apache Cassandra(R)
+ driver_version   | 4.13.0
+ hostname         | localhost
+ protocol_version | 5
+ request_count    | 7
+ ssl_cipher_suite | null
+ ssl_enabled      | False
+ ssl_protocol     | null
+ username         | anonymous
 
-(2 rows)
+(4 rows)
 ....
 
 Some examples of how `clients` can be used are:
@@ -130,29 +192,36 @@ upgrading and with `nodetool enableoldprotocolversions` and
 `nodetool disableoldprotocolversions` during upgrades.
 * To identify clients sending too many requests.
 * To find if SSL is enabled during the migration to and from ssl.
+* To identify all options the client is sending, e.g. APPLICATION_NAME and APPLICATION_VERSION
 
 The virtual tables may be described with `DESCRIBE` statement. The DDL
 listed however cannot be run to create a virtual table. As an example
 describe the `system_views.clients` virtual table:
 
 ....
-cqlsh:system_views> DESC TABLE system_views.clients;
-CREATE TABLE system_views.clients (
-  address inet,
-  connection_stage text,
-  driver_name text,
-  driver_version text,
-  hostname text,
-  port int,
-  protocol_version int,
-  request_count bigint,
-  ssl_cipher_suite text,
-  ssl_enabled boolean,
-  ssl_protocol text,
-  username text,
-  PRIMARY KEY (address, port)) WITH CLUSTERING ORDER BY (port ASC)
-  AND compaction = {'class': 'None'}
-  AND compression = {};
+cqlsh> DESCRIBE TABLE system_views.clients;
+
+/*
+Warning: Table system_views.clients is a virtual table and cannot be recreated with CQL.
+Structure, for reference:
+VIRTUAL TABLE system_views.clients (
+    address inet,
+    port int,
+    client_options frozen<map<text, text>>,
+    connection_stage text,
+    driver_name text,
+    driver_version text,
+    hostname text,
+    protocol_version int,
+    request_count bigint,
+    ssl_cipher_suite text,
+    ssl_enabled boolean,
+    ssl_protocol text,
+    username text,
+    PRIMARY KEY (address, port)
+) WITH CLUSTERING ORDER BY (port ASC)
+    AND comment = 'currently connected clients';
+*/
 ....
 
 === Caches Virtual Table