This feature is in preview. This feature is subject to change. To share feedback and/or issues, contact Support.
On a secure cluster, you must be an admin user to access this area of the DB Console. Refer to DB Console security.
New in v23.1: The Key Visualizer page of the DB Console provides access to the Key Visualizer tool, which enables the visualization of current and historical key-value (KV) traffic serviced by your cluster.
The Key Visualizer is a useful troubleshooting tool when experiencing performance problems with your cluster, surfacing historical and current KV hot spots in your keyspace, drawing attention to range splits, and highlighting potentially-unnecessary full-table scans that might benefit from the creation of a targeted index, among others.
The Key Visualizer is disabled by default. Once enabled, the Key Visualizer continuously collects keyspace usage data across your cluster in the background at a configurable sampling rate. Data shown in the Key Visualizer is retained for a maximum period of seven days.
To access the Key Visualizer, navigate to the DB Console and click Advanced Debug in the left-hand navigation, then click Key Visualizer under the Even More Advanced Debugging heading.
Required privileges
To view the Advanced Debug page and work with the Key Visualizer, the user must be a member of the admin role or must have the VIEWDEBUG system privilege defined.
Enable the Key Visualizer
To use the Key Visualizer, the keyvisualizer.enabled cluster setting must be set to true, using the SET CLUSTER SETTING statement:
> SET CLUSTER SETTING keyvisualizer.enabled = true;
The Key Visualizer is disabled by default.
Key Visualizer features
Once you have enabled the Key Visualizer, CockroachDB will begin monitoring keyspace usage across your cluster. Data is only collected while the Key Visualizer is enabled; you cannot visualize data from a time period before you enabled it.
When navigating to the Key Visualizer page in the DB Console, after a brief loading time, CockroachDB will present the collected data in a visualization designed to help you see data traffic trends at a glance.
The Key Visualizer presents the following information:
The entire table data keyspace is represented on the Y-axis, and is broken up into buckets representing whole ranges of the keyspace, or aggregated ranges if the number of ranges in the keyspace exceeds the configured number of buckets.
Time is represented on the X-axis, with its granularity (i.e., frequency of data collection) being controlled by the configured sample period.
Keyspace activity is visualized on a color scale from black to red, representing "cold" and "hot" respectively. Thus, a range shown in bright red indicates a hot spot, while a range shown in black indicates a range with little to no active reads or writes. Hot spots are identified relative to other ranges; for example, a range that receives one write per minute could be considered a hot spot if the rest of the ranges on the cluster aren't receiving any. A range shown in red is therefore not necessarily itself indicative of a problem, but it may help to narrow a problem down to a specific range or group of ranges when troubleshooting cluster performance.
Boundaries between buckets and time samples appear as grey lines. You can disable the drawing of these lines by deselecting the Show span boundaries checkbox below the Key Visualizer.
You can zoom in to focus on a particular range or sample period, or zoom out to see the entire keyspace at once, up to the maximum historical data retention period of seven days.
Hovering over a range in the Key Visualizer presents a tooltip with the start key, end key, number of requests, and timestamp of the recorded sample.
Key Visualizer customization
Beyond the keyvisualizer.enabled cluster setting, which must be enabled in order to use the Key Visualizer, there are two additional cluster settings that may be adjusted to control its behavior:
| Cluster Setting | Description |
|---|---|
keyvisualizer.sample_interval |
Controls the frequency at which the Key Visualizer collects samples. Default: 5m |
keyvisualizer.max_buckets |
Controls the maximum number of buckets in a sample. This value can range from 1 to 1024.Default: 256 |
Together, these cluster settings control the sampling resolution, or granularity, of the key data that the Key Visualizer collects and presents.
If your cluster has a large number of ranges, and the storage headroom to store the increased historical data, you might increase keyvisualizer.max_buckets to get more granularity in the visualizer, making pinpointing a specific problematic key range easier. Similarly, you might lower keyvisualizer.sample_interval to achieve more frequent samples, identifying changes between recorded samples more closely to when they actually occurred.
If your cluster has limited storage space available, you might decrease keyvisualizer.max_buckets and raise keyvisualizer.sample_interval to effectively store less collected data, at the cost of the Key Visualizer presenting a broader, less granular view of the keyspace.
If you adjust either of these values, new keyspace activity data collected by the Key Visualizer will reflect the new values, but previously-collected activity data will remain unchanged.
Troubleshooting performance with the Key Visualizer
When troubleshooting a performance issue with your cluster, use the Key Visualizer to identify which range or ranges in your keyspace to focus on. If needed, consider adjusting the Key Visualizer's granularity of data collection to more closely focus on a problematic range of keys if necessary, especially if the keyspace is very large and you have the storage headroom in your cluster to store the additional sample data.
The Key Visualizer was designed to make potentially problematic ranges stand out visually; as such, bright red spot are generally good places to begin a performance investigation. For example, consider the following cases:
Identifying hot spots
The following image shows the Key Visualizer highlighting a series of hot spots: ranges with much higher-than-average write rates as compared to the rest of the cluster.
Remediation: If you've identified a potentially-problematic range as a hot spot, follow the recommended best practices to reduce hot spots. In the case of the screenshot above, the increased write cadence is due to a series of range splits, where a range experiencing a large volume of incoming writes is splitting its keyspace to accommodate the growing range. This is often part of normal operation, but can be indicative of a data modeling issue if the range split is unexpected or causing cluster performance issues.
Identifying full table scans
The following image shows the Key Visualizer highlighting a full-table scan, where the lack of an appropriate index causes the query planner to need to scan the entire table to find the requested records in a query. This can be seen most clearly by the cascading series of bright red ranges that proceed in diagonal fashion to each other, such as the series of three shown at the mouse cursor. This cascade represents the sequential scan of contiguous ranges in the keyspace as the query planner attempts to locate requested data without an index.
Remediation: If you've identified a full table scan, follow the guidance to optimize statement performance. You can also analyze your queries with EXPLAIN to investigate if an index was used in the execution of the query.
See also
Was this helpful?
