Doc changes for tenant-level statistics

Why are we implementing it? (sales eng)

While you can monitor a node or a table it is not easy to track usage statistics of a tenant. With the citus_stat_tenants users will be able to which tenants is running how many queries and how much CPU they use in a given period.

What are the typical use cases?

Multi tenant workload user trying to find the tenants with the highest query counts and CPU usage.

Communication goals (e.g. detailed howto vs orientation)

Good locations for content in docs structure

How does this work? (devs)

The monitor tracks SELECT, INSERT, DELETE, and UPDATE queries and records the read count, query count and total CPU usage per tenant within time some time buckets. The top citus.stat_tenants_limit number of tenants are kept in the monitor. The current period and last period are recorded and after citus.stat_tenants_period seconds they are deleted.

Example sql

First run some queries for some tenants

INSERT INTO dist_table(tenant_id) VALUES (1);
INSERT INTO dist_table(tenant_id) VALUES (1);
INSERT INTO dist_table(tenant_id) VALUES (2);

SELECT count(*) FROM dist_table WHERE tenant_id = 1;
 count
-------
     2
(1 row)

Query the monitor

SELECT tenant_attribute, read_count_in_this_period, query_count_in_this_period, cpu_usage_in_this_period
FROM citus_stat_tenants;

 tenant_attribute | read_count_in_this_period | query_count_in_this_period | cpu_usage_in_this_period
------------------+---------------------------+----------------------------+--------------------------
 1                |                         1 |                          3 |                 0.000883
 2                |                         0 |                          1 |                 0.000144
(2 rows)

Corner cases, gotchas

You need to set citus.stat_tenants_track to 'all' in all nodes for monitor to work. Only SELECT, INSERT, UPDATE, and DELETE queries with a single tenant are counted. Users need to regularly check the monitor because after only current period and last period are recorded, they are deleted after one more period passes.

Are there relevant blog posts or outside documentation about the concept/feature?

Not yet

Link to relevant commits and regression tests if applicable

https://github.com/citusdata/citus/commit/52ad2d08c708954f73c8b0eb101a37ae8ef63b06 https://github.com/citusdata/citus/blob/main/src/test/regress/sql/citus_stat_tenants.sql

citusdata / citus_docs